scratch-l10n 6.1.93 → 6.1.95

package/scripts/lib/help-utils.mts

@@ -2,16 +2,30 @@
  * @file
  * Helper functions for syncing Freshdesk knowledge base articles with Transifex
  */
-import { promises as fsPromises, appendFileSync } from 'fs'
+import { promises as fsPromises } from 'fs'
 import { mkdirp } from 'mkdirp'
-import FreshdeskApi, { FreshdeskArticleCreate, FreshdeskArticleStatus, FreshdeskFolder } from './freshdesk-api.mts'
+import { messageOf } from './errors.mts'
+import FreshdeskApi, {
+  FreshdeskArticleCreate,
+  FreshdeskArticleStatus,
+  FreshdeskFolder,
+  logAuthenticatedAgent,
+} from './freshdesk-api.mts'
 import { TransifexStringKeyValueJson, TransifexStringsKeyValueJson, TransifexStrings } from './transifex-formats.mts'
 import { TransifexResourceObject } from './transifex-objects.mts'
 import { txPull, txResourcesObjects, txAvailableLanguages } from './transifex.mts'
+import { emitWarning } from './warnings.mts'
 
 const FD = new FreshdeskApi('https://mitscratch.freshdesk.com', process.env.FRESHDESK_TOKEN ?? '')
 const TX_PROJECT = 'scratch-help'
 
+/**
+ * Log which agent the configured Freshdesk token authenticates as, to aid in diagnosing permission
+ * problems. Never throws.
+ * @returns a promise that resolves once the agent has been logged
+ */
+export const logFreshdeskAgent = (): Promise<void> => logAuthenticatedAgent(FD)
+
 const freshdeskLocale = (locale: string): string => {
   // map between Transifex locale and Freshdesk. Two letter codes are usually fine
   const localeMap: Record<string, string> = {
@@ -46,13 +60,6 @@ const parseIntOrThrow = (str: string, radix: number) => {
   return num
 }
 
-const emitWarning = (warning: string) => {
-  console.warn(warning)
-  if (process.env.WARNINGS_FILE) {
-    appendFileSync(process.env.WARNINGS_FILE, warning + '\n')
-  }
-}
-
 /**
  * Pull metadata from Transifex for the scratch-help project
  * @returns Promise for a results object containing:
@@ -118,27 +125,42 @@ const serializeNameSave = async (
   warnedKeys: Set<string>,
 ): Promise<void> => {
   for (const [key, value] of Object.entries(strings)) {
-    // key is of the form <name>_<id>
-    const words = key.split('_')
-    const id = parseIntOrThrow(words[words.length - 1], 10)
-    if (!validIds.has(id)) {
-      const warnedKey = `${resource.attributes.name}:${id}`
-      if (!warnedKeys.has(warnedKey)) {
-        warnedKeys.add(warnedKey)
-        emitWarning(
-          `Warning: key "${key}" in Transifex resource "${resource.attributes.name}" refers to Freshdesk id ${id} which no longer exists. Remove this key from the Transifex resource.`,
-        )
+    // Handle each entry independently: a failure on one item (for example a translation the token
+    // is not allowed to write) must not abort the remaining names for this locale.
+    try {
+      // key is of the form <name>_<id>
+      const words = key.split('_')
+      const id = parseIntOrThrow(words[words.length - 1], 10)
+      if (!validIds.has(id)) {
+        const warnedKey = `${resource.attributes.name}:${id}`
+        if (!warnedKeys.has(warnedKey)) {
+          warnedKeys.add(warnedKey)
+          emitWarning(
+            `Warning: key "${key}" in Transifex resource "${resource.attributes.name}" refers to Freshdesk id ${id} which no longer exists. Remove this key from the Transifex resource.`,
+          )
+        }
+        continue
       }
-      continue
-    }
-    let status
-    if (resource.attributes.name === 'categoryNames_json') {
-      status = await FD.updateCategoryTranslation(id, freshdeskLocale(locale), { name: value })
-    }
-    if (resource.attributes.name === 'folderNames_json') {
-      status = await FD.updateFolderTranslation(id, freshdeskLocale(locale), { name: value })
-    }
-    if (status === -1) {
+      let status
+      if (resource.attributes.name === 'categoryNames_json') {
+        status = await FD.updateCategoryTranslation(id, freshdeskLocale(locale), { name: value })
+      } else if (resource.attributes.name === 'folderNames_json') {
+        status = await FD.updateFolderTranslation(id, freshdeskLocale(locale), { name: value })
+      } else {
+        // Guard against silently dropping an unexpected resource: this function only knows how to
+        // write category and folder names. A new KEYVALUEJSON names resource would otherwise no-op
+        // while still reporting success.
+        throw new Error(`Unexpected names resource "${resource.attributes.name}"; don't know how to save it`)
+      }
+      if (status === -1) {
+        process.exitCode = 1
+      }
+    } catch (error) {
+      // The FreshdeskApi update method already logged the specific error. Record the failure so the
+      // job still exits non-zero, then move on to the next entry.
+      process.stdout.write(
+        `Failed to save an entry in ${resource.attributes.name} for ${locale} (key "${key}"): ${messageOf(error)}\n`,
+      )
       process.exitCode = 1
     }
   }
@@ -162,22 +184,30 @@ interface FreshdeskFolderInTransifex {
  */
 const serializeFolderSave = async (json: TransifexStrings<FreshdeskFolderInTransifex>, locale: string) => {
   for (const [idString, value] of Object.entries(json)) {
-    const id = parseIntOrThrow(idString, 10)
-    const body: FreshdeskArticleCreate = {
-      title: value.title.string,
-      description: value.description.string,
-      status: FreshdeskArticleStatus.published,
-    }
-    if (Object.prototype.hasOwnProperty.call(value, 'tags')) {
-      const tags = value.tags.string.split(',')
-      const validTags = tags.filter(tag => tag.length < 33)
-      if (validTags.length !== tags.length) {
-        emitWarning(`Warning: tags too long in ${id} for ${locale}`)
+    // Handle each article independently: a failure on one must not abort the rest for this locale.
+    try {
+      const id = parseIntOrThrow(idString, 10)
+      const body: FreshdeskArticleCreate = {
+        title: value.title.string,
+        description: value.description.string,
+        status: FreshdeskArticleStatus.published,
       }
-      body.tags = validTags
-    }
-    const status = await FD.updateArticleTranslation(id, freshdeskLocale(locale), body)
-    if (status === -1) {
+      if (Object.prototype.hasOwnProperty.call(value, 'tags')) {
+        const tags = value.tags.string.split(',')
+        const validTags = tags.filter(tag => tag.length < 33)
+        if (validTags.length !== tags.length) {
+          emitWarning(`Warning: tags too long in ${id} for ${locale}`)
+        }
+        body.tags = validTags
+      }
+      const status = await FD.updateArticleTranslation(id, freshdeskLocale(locale), body)
+      if (status === -1) {
+        process.exitCode = 1
+      }
+    } catch (error) {
+      // The FreshdeskApi update method already logged the specific error. Record the failure so the
+      // job still exits non-zero, then move on to the next article.
+      process.stdout.write(`Failed to save article ${idString} for ${locale}: ${messageOf(error)}\n`)
       process.exitCode = 1
     }
   }

package/scripts/lib/transifex.mts

@@ -3,6 +3,7 @@
  * Utilities for interfacing with Transifex API 3.
  */
 import { transifexApi, Collection, JsonApiResource } from '@transifex/api'
+import { messageOf } from './errors.mts'
 import { TransifexStrings } from './transifex-formats.mts'
 import { TransifexLanguageObject, TransifexResourceObject } from './transifex-objects.mts'
 
@@ -17,6 +18,98 @@ transifexApi.setup({
   auth: process.env.TX_TOKEN,
 })
 
+/** Base delay for exponential backoff between transient-error retries, in milliseconds. */
+const TX_RETRY_BASE_MS = 1_000
+/** Maximum number of attempts for an operation that fails with a transient (retryable) error. */
+const TX_MAX_TRANSIENT_RETRIES = 5
+/** How often to poll an async upload for completion, in milliseconds. */
+const TX_UPLOAD_POLL_INTERVAL_MS = 2_000
+/**
+ * Overall budget for a single async upload to reach a terminal state, in milliseconds.
+ * This bounds the poll loop so a stuck upload fails fast (with a clear message) instead of
+ * polling forever — the workflow's `timeout-minutes` is only a last-resort backstop.
+ */
+const TX_UPLOAD_TIMEOUT_MS = 5 * 60_000
+/** Per-request timeout for downloading a resource from the CDN, in milliseconds. */
+const TX_DOWNLOAD_TIMEOUT_MS = 60_000
+
+const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+
+/**
+ * Decide whether an error is worth retrying: server-side 5xx, rate limiting (429), or a transient
+ * network failure. Client errors (4xx other than 429) are not retried — they won't fix themselves.
+ * @param err - the thrown error, from the Transifex SDK (`JsonApiException`), `fetch`, or the network stack
+ * @returns true if retrying the same operation might succeed
+ */
+const isTransientError = (err: unknown): boolean => {
+  const e = (err ?? {}) as {
+    statusCode?: number
+    status?: number
+    code?: string
+    name?: string
+    cause?: { code?: string }
+  }
+  // A `fetch` aborted by `AbortSignal.timeout` rejects with a `TimeoutError` that carries no status
+  // or code; the only abort in this module is that timeout, so treat it (and a bare abort) as worth
+  // retrying.
+  if (e.name === 'TimeoutError' || e.name === 'AbortError') {
+    return true
+  }
+  const status = e.statusCode ?? e.status
+  if (typeof status === 'number') {
+    return status === 429 || (status >= 500 && status < 600)
+  }
+  const code = e.code ?? e.cause?.code
+  return (
+    code === 'ECONNRESET' ||
+    code === 'ECONNREFUSED' ||
+    code === 'ETIMEDOUT' ||
+    code === 'EAI_AGAIN' ||
+    code === 'UND_ERR_SOCKET' ||
+    code === 'UND_ERR_CONNECT_TIMEOUT'
+  )
+}
+
+/**
+ * Run an async operation, retrying with exponential backoff when it fails with a transient error.
+ * Non-transient errors (for example a 404) are re-thrown immediately so callers can handle them.
+ * @template T - the resolved type of the operation
+ * @param label - short description of the operation, used in retry log lines
+ * @param fn - the operation to run; called once per attempt
+ * @returns the resolved value of `fn`
+ */
+const withRetry = async function <T>(label: string, fn: () => Promise<T>): Promise<T> {
+  let lastError: unknown
+  for (let attempt = 1; attempt <= TX_MAX_TRANSIENT_RETRIES; attempt++) {
+    try {
+      return await fn()
+    } catch (err) {
+      lastError = err
+      if (!isTransientError(err) || attempt === TX_MAX_TRANSIENT_RETRIES) {
+        throw err
+      }
+      const delay = TX_RETRY_BASE_MS * 2 ** (attempt - 1)
+      console.warn(
+        `${label}: transient error on attempt ${attempt}/${TX_MAX_TRANSIENT_RETRIES}, ` +
+          `retrying in ${delay}ms: ${messageOf(err)}`,
+      )
+      await sleep(delay)
+    }
+  }
+  // Unreachable: the loop either returns or throws, but TypeScript can't prove it.
+  throw lastError
+}
+
+/**
+ * The subset of an async-upload resource instance that we poll. The SDK's generated types model
+ * `reload` as requiring an `include` argument, but at runtime it is optional; this shape lets us
+ * call `reload()` with no arguments while staying type-checked.
+ */
+interface AsyncUploadResource {
+  get(key: string): unknown
+  reload(): Promise<void>
+}
+
 /*
  * The Transifex JS API wraps the Transifex JSON API, and is built around the concept of a `Collection`.
  * A `Collection` begins as a URL builder: methods like `filter` and `sort` add query parameters to the URL.
@@ -111,24 +204,47 @@ export const txPull = async function <T>(
 ): Promise<TransifexStrings<T>> {
   let buffer: string | null = null
   try {
-    const url = await getResourceLocation(project, resource, locale, mode)
+    // Creating the download event itself polls Transifex until the file is ready; retry transient
+    // failures (5xx / network blips) so one bad response doesn't sink the whole pull.
+    const url = await withRetry(`txPull download event for ${resource}/${locale}`, () =>
+      getResourceLocation(project, resource, locale, mode),
+    )
+    let lastError: unknown
     for (let i = 0; i < 5; i++) {
       if (i > 0) {
-        console.log(`Retrying txPull download after ${i} failed attempt(s)`)
+        const delay = TX_RETRY_BASE_MS * 2 ** (i - 1)
+        console.log(
+          `Retrying txPull download for ${resource}/${locale} after ${i} failed attempt(s); waiting ${delay}ms`,
+        )
+        await sleep(delay)
       }
       try {
-        const response = await fetch(url)
+        const response = await fetch(url, { signal: AbortSignal.timeout(TX_DOWNLOAD_TIMEOUT_MS) })
         if (!response.ok) {
-          throw new Error(`Failed to download resource: ${response.statusText}`)
+          const err = new Error(
+            `Failed to download resource: HTTP ${response.status} ${response.statusText}`,
+          ) as Error & { status: number }
+          err.status = response.status
+          throw err
         }
         buffer = await response.text()
         break
       } catch (e) {
-        console.error(e, { project, resource, locale, buffer })
+        lastError = e
+        console.error(`txPull download attempt ${i + 1} failed for ${resource}/${locale}: ${messageOf(e)}`)
+        // Only 5xx / 429 / network / timeout failures are worth retrying. A non-transient failure
+        // (for example a 403 or 404) won't fix itself, so fail fast and surface the real cause
+        // instead of burning the remaining attempts.
+        if (!isTransientError(e)) {
+          throw e
+        }
       }
     }
-    if (!buffer) {
-      throw Error(`txPull download failed after 5 retries: ${url}`)
+    if (buffer === null) {
+      throw new Error(
+        `txPull download failed after 5 attempts for ${resource}/${locale} (${url}): ` +
+          `${(lastError as Error | undefined)?.message ?? 'unknown error'}`,
+      )
     }
     return JSON.parse(buffer) as TransifexStrings<T>
   } catch (e) {
@@ -205,10 +321,42 @@ export const txPush = async function (project: string, resource: string, sourceS
     },
   }
 
-  await transifexApi.ResourceStringsAsyncUpload.upload({
-    resource: resourceObj,
-    content: JSON.stringify(sourceStrings),
-  })
+  // `ResourceStringsAsyncUpload.upload()` creates the upload and then polls until its status is
+  // `succeeded`. That poll has no timeout and no exit for a `failed` status, so a rejected upload
+  // (or one stuck in `pending`) loops forever — historically until the CI job's 6-hour limit, and
+  // any transient 502 on a poll crashed the whole job with an unhelpful stack trace. We do the
+  // create-then-poll ourselves so we can bound it, retry transient blips, and surface the actual
+  // reason an upload failed.
+  const upload = (await withRetry(`txPush create upload for "${resource}"`, () =>
+    transifexApi.ResourceStringsAsyncUpload.create({
+      resource: resourceObj,
+      content: JSON.stringify(sourceStrings),
+      content_encoding: 'text',
+      // The generated type insists on id/attributes/relationships/links, but the upload resource
+      // takes this flatter shape — the same one `ResourceStringsAsyncUpload.upload()` passes through.
+    } as unknown as Parameters<typeof transifexApi.ResourceStringsAsyncUpload.create>[0]),
+  )) as unknown as AsyncUploadResource
+
+  const deadline = Date.now() + TX_UPLOAD_TIMEOUT_MS
+  for (;;) {
+    const status = upload.get('status') as string | undefined
+    if (status === 'succeeded') {
+      return
+    }
+    if (status === 'failed') {
+      // On failure the upload carries `errors` (and sometimes `details`) explaining why.
+      const errorInfo = upload.get('errors') ?? upload.get('details') ?? 'no error detail provided'
+      throw new Error(`Transifex upload failed for resource "${resource}": ${JSON.stringify(errorInfo)}`)
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Transifex upload for resource "${resource}" did not reach a terminal state within ` +
+          `${TX_UPLOAD_TIMEOUT_MS / 1000}s (last status: ${status ?? 'unknown'}).`,
+      )
+    }
+    await sleep(TX_UPLOAD_POLL_INTERVAL_MS)
+    await withRetry(`txPush poll upload for "${resource}"`, () => upload.reload())
+  }
 }
 
 /**

package/scripts/lib/warnings.mts

@@ -0,0 +1,26 @@
+/**
+ * @file
+ * Shared helper for reporting non-fatal problems during help sync.
+ */
+import { appendFileSync } from 'fs'
+import { messageOf } from './errors.mts'
+
+/**
+ * Log a warning to the console and, when the `WARNINGS_FILE` environment variable is set, append it
+ * to that file. CI reads the file after the sync to surface warnings in the job summary and to send
+ * a notification, so a warning is the right tool for a problem worth a human's attention that should
+ * not fail the run (for example, a resource we deliberately skip).
+ * @param warning - the warning message; a trailing newline is added when written to the file
+ */
+export const emitWarning = (warning: string): void => {
+  console.warn(warning)
+  if (process.env.WARNINGS_FILE) {
+    // The file write is best-effort: emitWarning is the non-fatal path (often called from a catch
+    // block), so a failed append must not turn a warning into a crash.
+    try {
+      appendFileSync(process.env.WARNINGS_FILE, warning + '\n')
+    } catch (error) {
+      console.warn(`Could not append to WARNINGS_FILE "${process.env.WARNINGS_FILE}": ${messageOf(error)}`)
+    }
+  }
+}

package/scripts/tx-pull-help-names.mts

@@ -3,7 +3,7 @@
  * @file
  * Script to pull scratch-help translations from transifex and push to FreshDesk.
  */
-import { getInputs, getValidFreshdeskIds, saveItem, localizeNames } from './lib/help-utils.mts'
+import { getInputs, getValidFreshdeskIds, saveItem, localizeNames, logFreshdeskAgent } from './lib/help-utils.mts'
 
 const args = process.argv.slice(2)
 
@@ -22,6 +22,8 @@ if (!process.env.TX_TOKEN || !process.env.FRESHDESK_TOKEN || args.length > 0) {
   process.exit(1)
 }
 
+await logFreshdeskAgent()
+
 const [{ languages, names }, { validCategoryIds, validFolderIds }] = await Promise.all([
   getInputs(),
   getValidFreshdeskIds(),

package/scripts/tx-push-help.mts

@@ -3,9 +3,15 @@
  * @file
  * Script get Knowledge base articles from Freshdesk and push them to transifex.
  */
-import FreshdeskApi, { FreshdeskArticleStatus, FreshdeskCategory, FreshdeskFolder } from './lib/freshdesk-api.mts'
+import FreshdeskApi, {
+  FreshdeskArticleStatus,
+  FreshdeskCategory,
+  FreshdeskFolder,
+  logAuthenticatedAgent,
+} from './lib/freshdesk-api.mts'
 import { TransifexStringsKeyValueJson, TransifexStringsStructuredJson } from './lib/transifex-formats.mts'
 import { txPush, txCreateResource, JsonApiException } from './lib/transifex.mts'
+import { emitWarning } from './lib/warnings.mts'
 
 const args = process.argv.slice(2)
 
@@ -30,6 +36,17 @@ const TX_PROJECT = 'scratch-help'
 const categoryNames: TransifexStringsKeyValueJson = {}
 const folderNames: TransifexStringsKeyValueJson = {}
 
+// Collect per-resource failures instead of aborting on the first one, so a single failing folder or
+// category (for example one the token cannot access) still lets every other resource sync. The
+// script fails at the end if anything meaningful failed, so a persistent problem is surfaced for
+// investigation rather than silently dropped.
+const failures: { context: string; message: string }[] = []
+const recordFailure = (context: string, error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`Error: ${context}: ${message}`)
+  failures.push({ context, message })
+}
+
 /**
  * Generate a transifex resource slug from the name and ID of a Freshdesk object.
  * Strips characters not allowed in Transifex slugs (only `[a-zA-Z0-9_-]` are permitted).
@@ -50,12 +67,22 @@ const txPushResource = async (
   articles: TransifexStringsStructuredJson | TransifexStringsKeyValueJson,
   type: string,
 ) => {
+  // Transifex rejects an upload with no extractable strings (`parse_error: No strings could be
+  // extracted`). That used to leave the upload stuck in a non-`succeeded` state forever, hanging
+  // the whole sync. An empty resource almost always means a Freshdesk folder with no published
+  // articles, which is a content situation rather than a sync failure: warn and skip it.
+  if (Object.keys(articles).length === 0) {
+    emitWarning(`Skipping Transifex resource "${name}": no strings to push (empty content).`)
+    return
+  }
+
   const resourceData = {
     slug: name,
     name: name,
     i18nType: type,
-    priority: 0, // default to normal priority
-    content: articles,
+    // `txCreateResource` reads `sourceStrings` (not `content`); passing the wrong key left a newly
+    // created resource empty until a later run populated it.
+    sourceStrings: articles,
   }
 
   try {
@@ -77,9 +104,18 @@ const txPushResource = async (
  * @param categories - array of categories the folders belong to
  * @returns flattened list of folders from all requested categories
  */
-const getFolders = async (categories: FreshdeskCategory[]) => {
-  const categoryFolders = await Promise.all(categories.map(category => FD.listFolders(category)))
-  return ([] as FreshdeskCategory[]).concat(...categoryFolders)
+const getFolders = async (categories: FreshdeskCategory[]): Promise<FreshdeskFolder[]> => {
+  const categoryFolders = await Promise.all(
+    categories.map(async (category): Promise<FreshdeskFolder[]> => {
+      try {
+        return await FD.listFolders(category)
+      } catch (error) {
+        recordFailure(`list folders for category "${category.name}" (id ${category.id})`, error)
+        return []
+      }
+    }),
+  )
+  return categoryFolders.flat()
 }
 
 /**
@@ -87,7 +123,8 @@ const getFolders = async (categories: FreshdeskCategory[]) => {
  * @param folder - The folder object
  */
 const saveArticles = async (folder: FreshdeskFolder) => {
-  await FD.listArticles(folder).then(async json => {
+  try {
+    const json = await FD.listArticles(folder)
     const txArticles = json.reduce((strings: TransifexStringsStructuredJson, current) => {
       if (current.status === FreshdeskArticleStatus.published) {
         strings[String(current.id)] = {
@@ -106,13 +143,15 @@ const saveArticles = async (folder: FreshdeskFolder) => {
     }, {})
     process.stdout.write(`Push ${folder.name} articles to Transifex\n`)
     await txPushResource(`${makeTxSlug(folder)}_json`, txArticles, 'STRUCTURED_JSON')
-  })
+  } catch (error) {
+    recordFailure(`folder "${folder.name}" (id ${folder.id})`, error)
+  }
 }
 
 /**
  * @param folders - Array of folders containing articles to be saved
  */
-const saveArticleFolders = async (folders: FreshdeskCategory[]) => {
+const saveArticleFolders = async (folders: FreshdeskFolder[]) => {
   await Promise.all(folders.map(folder => saveArticles(folder)))
 }
 
@@ -133,12 +172,25 @@ const syncSources = async () => {
       })
       process.stdout.write('Push category and folder names to Transifex\n')
       await Promise.all([
-        txPushResource('categoryNames_json', categoryNames, 'KEYVALUEJSON'),
-        txPushResource('folderNames_json', folderNames, 'KEYVALUEJSON'),
+        txPushResource('categoryNames_json', categoryNames, 'KEYVALUEJSON').catch(error =>
+          recordFailure('categoryNames_json', error),
+        ),
+        txPushResource('folderNames_json', folderNames, 'KEYVALUEJSON').catch(error =>
+          recordFailure('folderNames_json', error),
+        ),
       ])
       return data
     })
     .then(saveArticleFolders)
 }
 
+await logAuthenticatedAgent(FD)
 await syncSources()
+
+if (failures.length > 0) {
+  console.error(`\n${failures.length} resource(s) failed to push to Transifex:`)
+  for (const failure of failures) {
+    console.error(`  - ${failure.context}: ${failure.message}`)
+  }
+  process.exitCode = 1
+}

package/www/scratch-website.general-l10njson/hy.json

@@ -49,7 +49,7 @@
     "general.loadMore": "Բեռնել ավելին",
     "general.learnMore": "Սովորել ավելին",
     "general.male": "Արական",
-    "general.membership": "Membership",
+    "general.membership": "Անդամակցություն",
     "general.messages": "Հաղորդագրություն",
     "general.mitAccessibility": "MIT Accessibility",
     "general.month": "Ամիս",