Convert src/languages/lib to TypeScript (#56572)

Author: heiskr

src/frame/middleware/context/glossaries.ts

@@ -60,7 +60,7 @@ export default async function glossaries(req: ExtendedRequest, res: Response, ne
           )
         }
         description = await executeWithFallback(
-          req.context,
+          req.context!,
           () => liquid.parseAndRender(description, req.context),
           (enContext: Context) => {
             const { term } = glossary

src/languages/lib/correct-translation-content.js renamed to src/languages/lib/correct-translation-content.ts

@@ -7,7 +7,19 @@
  * It looks for easy "low hanging fruit" that we can correct for.
  *
  */
-export function correctTranslatedContentStrings(content, englishContent, context = {}) {
+
+interface CorrectionContext {
+  code?: string
+  dottedPath?: string
+  relativePath?: string
+  [key: string]: any
+}
+
+export function correctTranslatedContentStrings(
+  content: string,
+  englishContent: string,
+  context: CorrectionContext = {},
+): string {
   // A lot of translations have corruptions around the AUTOTITLE links.
   // We've requested that these are corrected back but as a temporary
   // solution we'll manually recover now.
@@ -294,7 +306,7 @@ export function correctTranslatedContentStrings(content, englishContent, context
     const keyString = '5DE3 E050 9C47 EA3C F04A 42D3 4AEE 18F8 3AFD EB23'
     const translatedSentences = [
       // ru
-      'Полный отпечаток ключа — `' + keyString + '`.',
+      'Полный отпечаток ключа\u00A0\u2014 `' + keyString + '`.',
       // ko
       `키의 전체 지문은 \`${keyString}\`입니다.`,
       // es
@@ -306,7 +318,7 @@ export function correctTranslatedContentStrings(content, englishContent, context
       // ja
       `キーの完全な指紋は、\`${keyString}\` です。`,
       // fr
-      `L’empreinte digitale complète de la clé est \`${keyString}\`.`,
+      `L\u2019empreinte digitale complète de la clé est \`${keyString}\`.`,
       // de
       `Der vollständige Fingerabdruck des Schlüssels ist \`${keyString}\`.`,
     ]

src/languages/lib/get-english-headings.js renamed to src/languages/lib/get-english-headings.ts

@@ -1,20 +1,40 @@
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { toString } from 'mdast-util-to-string'
 import { visit } from 'unist-util-visit'
+import type { Node } from 'unist'
 
 import findPage from '@/frame/lib/find-page'
 import { getDataByLanguage } from '@/data-directory/lib/get-data'
+import type { Context } from '@/types'
+
+interface HeadingNode extends Node {
+  type: 'heading'
+  depth: number
+}
+
+interface PageWithMarkdown {
+  relativePath: string
+  markdown: string
+}
+
+interface GlossaryTerm {
+  term: string
+  slug: string
+}
 
 // for any translated page, first get corresponding English markdown
 // then get the headings on both the translated and English pageMap
 // finally, create a map of translation:English for all headings on the page
-export default function getEnglishHeadings(page, context) {
+export default function getEnglishHeadings(
+  page: PageWithMarkdown,
+  context: Context,
+): Record<string, string> | undefined {
   // Special handling for glossaries, because their headings are
   // generated programmatically.
   if (page.relativePath.endsWith('/github-glossary.md')) {
     // Return an object of `{ localized-term: english-slug }`
-    const languageGlossary = getDataByLanguage('glossaries.external', 'en')
-    return languageGlossary.reduce((prev, curr) => {
+    const languageGlossary = getDataByLanguage('glossaries.external', 'en') as GlossaryTerm[]
+    return languageGlossary.reduce((prev: Record<string, string>, curr: GlossaryTerm) => {
       prev[curr.term] = curr.slug
       return prev
     }, {})
@@ -35,20 +55,21 @@ export default function getEnglishHeadings(page, context) {
   if (!englishHeadings.length) return
 
   // return a map from translation:English
-  return Object.assign(
-    ...translatedHeadings.map((k, i) => ({
-      [k]: englishHeadings[i],
-    })),
-  )
+  const headingMap: Record<string, string> = {}
+  translatedHeadings.forEach((k: string, i: number) => {
+    headingMap[k] = englishHeadings[i]
+  })
+  return headingMap
 }
 
-function getHeadings(markdown) {
+function getHeadings(markdown: string): string[] {
   const ast = fromMarkdown(markdown)
-  const headings = []
+  const headings: string[] = []
 
-  visit(ast, (node) => {
+  visit(ast, (node: Node) => {
     if (node.type !== 'heading') return
-    if (![2, 3, 4].includes(node.depth)) return
+    const headingNode = node as HeadingNode
+    if (![2, 3, 4].includes(headingNode.depth)) return
     headings.push(toString(node))
   })
 

src/languages/lib/render-with-fallback.js renamed to src/languages/lib/render-with-fallback.ts

@@ -1,26 +1,47 @@
 import { renderContent } from '@/content-render/index'
 import Page from '@/frame/lib/page'
 import { TitleFromAutotitleError } from '@/content-render/unified/rewrite-local-links'
+import type { Context } from '@/types'
 
 export class EmptyTitleError extends Error {}
 
+interface LiquidToken {
+  file?: string
+  getPosition?: () => [number, number]
+}
+
+interface LiquidError extends Error {
+  token?: LiquidToken
+  originalError?: Error
+}
+
+interface RenderOptions {
+  throwIfEmpty?: boolean
+  textOnly?: boolean
+  cache?: boolean | ((template: string, context: any) => string)
+  [key: string]: any
+}
+
 const LIQUID_ERROR_NAMES = new Set(['RenderError', 'ParseError', 'TokenizationError'])
-export const isLiquidError = (error) =>
-  error instanceof Error && error.name && LIQUID_ERROR_NAMES.has(error.name)
+export const isLiquidError = (error: unknown): error is LiquidError =>
+  error instanceof Error && error.name !== undefined && LIQUID_ERROR_NAMES.has(error.name)
 
-const isAutotitleError = (error) => error instanceof TitleFromAutotitleError
-const isEmptyTitleError = (error) => error instanceof EmptyTitleError
+const isAutotitleError = (error: unknown): error is TitleFromAutotitleError =>
+  error instanceof TitleFromAutotitleError
 
-const isFallbackableError = (error) =>
+const isEmptyTitleError = (error: unknown): error is EmptyTitleError =>
+  error instanceof EmptyTitleError
+
+const isFallbackableError = (error: unknown): boolean =>
   isLiquidError(error) || isAutotitleError(error) || isEmptyTitleError(error)
 
 /**
  * Creates an HTML comment with translation fallback error information
  * Includes detailed debugging information for translators
  */
-export function createTranslationFallbackComment(error, property) {
+export function createTranslationFallbackComment(error: Error, property: string): string {
   const errorType = error.name || 'UnknownError'
-  let errorDetails = []
+  const errorDetails: string[] = []
 
   // Add basic error information
   errorDetails.push(`TRANSLATION_FALLBACK`)
@@ -82,14 +103,21 @@ export function createTranslationFallbackComment(error, property) {
 // function. This means, we can know, in the middleware (which is a
 // higher level than `lib/`) how to use the URL to figure out the
 // equivalent English page instance.
-export async function renderContentWithFallback(page, property, context, options) {
+export async function renderContentWithFallback(
+  // Using `any` type for page because the actual Page class from @/frame/lib/page
+  // has more properties than the Page interface defined in @/types, causing type conflicts
+  page: any,
+  property: string,
+  context: Context,
+  options?: RenderOptions,
+): Promise<string> {
   if (!(page instanceof Page)) {
     throw new Error(`The first argument has to be Page instance (not ${typeof page})`)
   }
   if (typeof property !== 'string') {
     throw new Error(`The second argument has to be a string (not ${typeof property})`)
   }
-  const template = page[property]
+  const template = (page as any)[property] as string
   try {
     const output = await renderContent(template, context, options)
     if (options && options.throwIfEmpty && !output.trim()) {
@@ -101,7 +129,7 @@ export async function renderContentWithFallback(page, property, context, options
     // on English for.
     if (isFallbackableError(error) && context.getEnglishPage) {
       const enPage = context.getEnglishPage(context)
-      const englishTemplate = enPage[property]
+      const englishTemplate = (enPage as any)[property] as string
       // If you don't change the context, it'll confuse the liquid plugins
       // like `data.js` that uses `environment.scope.currentLanguage`
       const enContext = Object.assign({}, context, { currentLanguage: 'en' })
@@ -112,7 +140,7 @@ export async function renderContentWithFallback(page, property, context, options
       // Add HTML comment with error details for non-English languages
       // Skip for textOnly rendering to avoid breaking plain text output
       if (context.currentLanguage !== 'en' && !options?.textOnly) {
-        const errorComment = createTranslationFallbackComment(error, property)
+        const errorComment = createTranslationFallbackComment(error as Error, property)
         return errorComment + '\n' + fallbackContent
       }
 
@@ -137,19 +165,23 @@ export async function renderContentWithFallback(page, property, context, options
 //     (enContext) => renderContent(enTrack.title, enContext, renderOpts)
 //   )
 //
-export async function executeWithFallback(context, callable, fallback) {
+export async function executeWithFallback<T>(
+  context: Context,
+  callable: (context: Context) => T | Promise<T>,
+  fallback: (enContext: Context) => T | Promise<T>,
+): Promise<T> {
   try {
-    return await callable(context)
+    return await Promise.resolve(callable(context))
   } catch (error) {
     if (isFallbackableError(error) && context.currentLanguage !== 'en') {
       const enContext = Object.assign({}, context, { currentLanguage: 'en' })
-      const fallbackContent = await fallback(enContext)
+      const fallbackContent = await Promise.resolve(fallback(enContext))
 
       // Add HTML comment with error details for non-English languages
       // Only for HTML content (detected by presence of HTML tags)
       if (typeof fallbackContent === 'string' && /<[^>]+>/.test(fallbackContent)) {
-        const errorComment = createTranslationFallbackComment(error, 'content')
-        return errorComment + '\n' + fallbackContent
+        const errorComment = createTranslationFallbackComment(error as Error, 'content')
+        return (errorComment + '\n' + fallbackContent) as T
       }
 
       return fallbackContent