From 93ad77089bec416fa27473f0309a9eb5b99c7165 Mon Sep 17 00:00:00 2001 From: Benjamin Lu Date: Wed, 14 Oct 2026 14:05:34 -0700 Subject: [PATCH 1/4] ci(website): open translation PRs automatically Generate website translations when English catalogs or translation config change on main, and daily, into one regenerated PR. Drop the test that required Chinese copy for every English string: English fallback covers the gap until the generated PR merges, and the rule pushed agents to hand-write translations. Agent and README guidance now say to write English only. A string still rejected after every retry is now left out of its file instead of discarding the whole entry file for that locale, so one bad translation no longer stalls every other string. --- .github/workflows/i18n-update-website.yaml | 40 +++++++++- apps/website/AGENTS.md | 6 +- apps/website/README.md | 24 ++++-- apps/website/src/i18n/translations.test.ts | 17 ----- scripts/i18n/translate.test.ts | 36 ++++++--- scripts/i18n/translate.ts | 21 ++---- .../i18n/update-locales.integration.test.ts | 46 +++++++++--- scripts/i18n/update-locales.test.ts | 15 ++-- scripts/i18n/update-locales.ts | 75 ++++++++++++++----- src/locales/CONTRIBUTING.md | 4 +- 10 files changed, 189 insertions(+), 95 deletions(-) diff --git a/.github/workflows/i18n-update-website.yaml b/.github/workflows/i18n-update-website.yaml index edb51940206..c92cb52a4e6 100644 --- a/.github/workflows/i18n-update-website.yaml +++ b/.github/workflows/i18n-update-website.yaml @@ -2,6 +2,14 @@ name: 'i18n: Update Website' on: + push: + branches: [main] + paths: + - 'apps/website/src/locales/en/*.json' + - 'apps/website/src/config/locales.ts' + - 'apps/website/src/config/translation.ts' + schedule: + - cron: '17 10 * * *' workflow_dispatch: permissions: @@ -13,8 +21,9 @@ concurrency: jobs: update-locales: - if: github.ref_type == 'branch' + if: github.repository == 'Comfy-Org/ComfyUI_frontend' && github.ref_type == 'branch' runs-on: ubuntu-latest + timeout-minutes: 30 steps: - name: Checkout repository uses: actions/checkout@v7 @@ -28,12 +37,33 @@ jobs: uses: ./.github/actions/setup-frontend - name: Update translations + id: translate + continue-on-error: true run: pnpm --filter @comfyorg/website locale env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + - name: Open the translation PR + if: github.ref_name == 'main' + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 + with: + token: ${{ secrets.PR_GH_TOKEN }} + branch: i18n/website-locales + add-paths: apps/website/src/locales/ + commit-message: 'fix(website): update locale catalogs' + title: 'fix(website): update locale catalogs' + labels: area:i18n + assignees: benceruleanlu + body: | + ## Summary + + Translations of new or changed English website copy, generated by [this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}). + + Every run regenerates this branch from main, so merge it before editing a translation by hand. + - name: Commit updated locales id: commit + if: github.ref_name != 'main' run: | git add apps/website/src/locales/ if git diff --cached --quiet; then exit 0; fi @@ -42,8 +72,6 @@ jobs: commit -m 'Update website locales' echo "committed=true" >> "$GITHUB_OUTPUT" - # Only this step sees the push token: the steps above run scripts from - # the dispatched branch - name: Push updated locales if: steps.commit.outputs.committed == 'true' env: @@ -52,3 +80,9 @@ jobs: run: | git push "https://x-access-token:${PR_GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \ "HEAD:refs/heads/$TARGET_BRANCH" + + - name: Fail if some strings were not translated + if: steps.translate.outcome == 'failure' + run: | + echo "::error::Some website strings were not translated; the Update translations step lists them. Everything else was published, and the rest retry on the next run." + exit 1 diff --git a/apps/website/AGENTS.md b/apps/website/AGENTS.md index 39f98f532e7..ca7006aba98 100644 --- a/apps/website/AGENTS.md +++ b/apps/website/AGENTS.md @@ -36,8 +36,10 @@ file wins. These root rules do not apply here: vue-i18n message syntax), not in the app's root `src/locales/`. Read it with the request-bound `Astro.locals.t` in Astro or `translationsFor(locale).t` in Vue and TypeScript; never fill a placeholder with `.replace`. Write a literal - `@`, `|`, `{` or `}` as `{'@'}`, `{'|'}`, `{'{'}` or `{'}'}`. Add `en` and - `zh-CN` values for every new string. See the README's Localization section. + `@`, `|`, `{` or `}` as `{'@'}`, `{'|'}`, `{'{'}` or `{'}'}`. Write new and + changed copy in `en/main.json` only and never edit another locale's file: a + workflow translates English changes on main into a PR, and missing strings + render in English until it merges. See the README's Localization section. - The dev server is `pnpm --filter @comfyorg/website dev` on `http://localhost:4321`, not `pnpm dev` on 5173. The root `/verify-visually` command points at the wrong server for this site. diff --git a/apps/website/README.md b/apps/website/README.md index f69967340a2..aa9b92bf6a3 100644 --- a/apps/website/README.md +++ b/apps/website/README.md @@ -53,16 +53,14 @@ as the application's `src/locales/` at the repository root: API. Astro middleware binds `Astro.locals.t` to the request locale. In Vue and TypeScript, bind once with `translationsFor(locale).t`; each locale has its own composer because the site renders locales concurrently. Missing messages fall -back to English. The catalog test compiles every message and checks that each -eligible English message has Chinese copy. +back to English. The catalog test compiles every message in every locale. `main.json` is the catalog for each locale. Keep feature copy grouped under a nested feature key. -Add new English copy to the English catalog; translated copy lives in the -matching file under each locale. Every eligible English message requires a -Chinese entry. Excluded namespaces use English fallback when no translation -exists. The catalog tests enforce this distinction. +Write new and changed copy in the English catalog only. Do not add or edit +other locales by hand: the generation workflow below translates it after it +merges, and until then those strings render in English. Catalog files use two-space JSON indentation and a final newline. Legal and content pages render their sections in the order they appear in the catalog, so keep `en/main.json` in document order and never sort its keys. @@ -100,6 +98,15 @@ have no `/ja/` route yet. Generation never enables routes or indexing. ### Generating translations +The `i18n: Update Website` workflow runs when English catalogs or translation +config change on main, and daily. It opens or updates one +`fix(website): update locale catalogs` PR from the `i18n/website-locales` +branch. Each run regenerates that branch from main, so merge the PR before +editing its translations by hand. A string the model keeps getting wrong is +left out, so it renders in English, and is retried on the next run; the rest +of the file is still written. Running the workflow by hand on another branch +commits the translations to that branch instead. + Inside this package, run `pnpm locale:check` for an offline preflight, or `pnpm locale` with `OPENAI_API_KEY` to translate eligible missing or changed copy. Both scripts call the shared CLI in `scripts/i18n/update-locales.ts` with @@ -114,8 +121,9 @@ of the English last generated. Its `knownViolations` field lists accepted protected-token violations as JSON-encoded key paths, such as `["cloud","reason","1","title"]`. Use a clone with full history: if the recorded blob is missing, `locale:check` warns and skips change detection and token -validation for that file, and `pnpm locale` fails. When translation of an entry file fails, -its English, locale catalogs and manifest entry keep their previous contents. +validation for that file, and `pnpm locale` fails. When a translation request +for an entry file fails, its English, locale catalogs and manifest entry keep +their previous contents. Commit the generated English catalog, locale catalogs and manifest together. If you edit any of them after generation, run `pnpm locale` again before diff --git a/apps/website/src/i18n/translations.test.ts b/apps/website/src/i18n/translations.test.ts index ad8eb9cb27d..5be9cc4c043 100644 --- a/apps/website/src/i18n/translations.test.ts +++ b/apps/website/src/i18n/translations.test.ts @@ -3,7 +3,6 @@ import { describe, expect, it } from 'vitest' import type { Locale } from '@/config/locales' import { LOCALE_CODES } from '@/config/locales' -import { translationExclusions } from '@/config/translation' import { translationsFor } from './translations' type Catalog = { [key: string]: string | Catalog } @@ -113,22 +112,6 @@ describe('site translations', () => { }) describe.for(catalogs)('$file catalog', ({ english, messages }) => { - it('includes Chinese copy for every eligible English message', () => { - const chinese = messages['zh-CN'] ?? {} - const chineseKeys = new Set(leafMessages(chinese).map(([key]) => key)) - const missing = leafMessages(english) - .map(([key]) => key) - .filter( - (key) => - !chineseKeys.has(key) && - !translationExclusions.some( - (prefix) => key === prefix || key.startsWith(`${prefix}.`) - ) - ) - - expect(missing).toEqual([]) - }) - it.for(LOCALE_CODES)('renders every %s message', (locale: Locale) => { const i18n = createI18n({ legacy: false, diff --git a/scripts/i18n/translate.test.ts b/scripts/i18n/translate.test.ts index 92d63e6abf2..2899582dcb9 100644 --- a/scripts/i18n/translate.test.ts +++ b/scripts/i18n/translate.test.ts @@ -53,7 +53,7 @@ describe('translateLocaleItems', () => { ) ) } - const translations = await translateLocaleItems( + const { translated: translations } = await translateLocaleItems( locale, items, flaky, @@ -63,14 +63,21 @@ describe('translateLocaleItems', () => { expect(calls).toBe(2) }) - it('fails after exhausting rounds when tokens stay corrupted', async () => { + it('reports items still corrupted after the last round as failed', async () => { const corrupting: TranslateBatch = (_batchLocale, batch) => Promise.resolve( Object.fromEntries(batch.map((item) => [item.id, 'Bonjour name'])) ) - await expect( - translateLocaleItems(locale, items, corrupting, translationConfig) - ).rejects.toThrow(/failed for 1 strings/) + const { translated, failed } = await translateLocaleItems( + locale, + items, + corrupting, + translationConfig + ) + expect(translated.size).toBe(0) + expect(failed.map(({ context }) => context)).toEqual([ + 'main.json: greeting' + ]) }) it('retries empty translations', async () => { @@ -83,7 +90,7 @@ describe('translateLocaleItems', () => { ) ) } - const translations = await translateLocaleItems( + const { translated: translations } = await translateLocaleItems( locale, items, blankFirst, @@ -111,10 +118,15 @@ describe('translateLocaleItems', () => { inFlight-- return Object.fromEntries(batch.map((item) => [item.id, `t${item.id}`])) } - const translations = await translateLocaleItems(locale, sixItems, gated, { - ...translationConfig, - requestConcurrency: 2 - }) + const { translated: translations } = await translateLocaleItems( + locale, + sixItems, + gated, + { + ...translationConfig, + requestConcurrency: 2 + } + ) expect(translations.size).toBe(6) expect(maxInFlight).toBe(2) }) @@ -134,7 +146,7 @@ describe('translateLocaleItems', () => { let call = 0 const crossTalking: TranslateBatch = () => Promise.resolve(responses[call++] ?? {}) - const translations = await translateLocaleItems( + const { translated: translations } = await translateLocaleItems( locale, threeItems, crossTalking, @@ -193,7 +205,7 @@ describe('translateLocaleItems', () => { ) } - const translations = await translateLocaleItems( + const { translated: translations } = await translateLocaleItems( locale, [docsLink], correctsOnRetry, diff --git a/scripts/i18n/translate.ts b/scripts/i18n/translate.ts index 2fcd042fb5d..6584edf1c1b 100644 --- a/scripts/i18n/translate.ts +++ b/scripts/i18n/translate.ts @@ -391,8 +391,8 @@ export async function translateLocaleItems( | 'maxTranslationRounds' | 'strictProtectedTokens' > -): Promise> { - const results = new Map() +): Promise<{ translated: Map; failed: TranslationItem[] }> { + const translated = new Map() let remaining = [...items] for ( @@ -414,11 +414,11 @@ export async function translateLocaleItems( return Object.entries(response).filter(([id]) => requested.has(id)) } ) - const translated = new Map(responses.flat()) + const responded = new Map(responses.flat()) const failed: TranslationItem[] = [] for (const item of remaining) { - const value = translated.get(item.id) + const value = responded.get(item.id) const errors = value === undefined ? ['no translation returned'] @@ -428,7 +428,7 @@ export async function translateLocaleItems( strict: config.strictProtectedTokens }) if (value !== undefined && errors.length === 0) { - results.set(item.id, value) + translated.set(item.id, value) } else { failed.push({ ...item, @@ -439,14 +439,5 @@ export async function translateLocaleItems( remaining = failed } - if (remaining.length > 0) { - const details = remaining - .map((item) => ` ${item.context}`) - .slice(0, 20) - .join('\n') - throw new Error( - `Translation into ${locale.code} failed for ${remaining.length} strings after ${config.maxTranslationRounds} attempts:\n${details}` - ) - } - return results + return { translated, failed: remaining } } diff --git a/scripts/i18n/update-locales.integration.test.ts b/scripts/i18n/update-locales.integration.test.ts index d9f78f02b3b..1692e9f2d29 100644 --- a/scripts/i18n/update-locales.integration.test.ts +++ b/scripts/i18n/update-locales.integration.test.ts @@ -396,17 +396,6 @@ describe('failure isolation', () => { locale === 'zh-CN' && item.context.startsWith('a.json:') ), failures: ['zh-CN/a.json: provider unavailable'] - }, - { - label: 'every attempt corrupts a protected token', - translator: () => - createTranslator((locale, item) => - `[${locale}] ${item.source}`.replace(' {name}', '') - ), - failures: [ - 'ja/a.json: Translation into ja failed for 1 strings after 3 attempts', - 'zh-CN/a.json: Translation into zh-CN failed for 1 strings after 3 attempts' - ] } ])( 'discards one entry file when $label while another file is written', @@ -448,6 +437,41 @@ describe('failure isolation', () => { ) }) +describe('strings rejected on every attempt', () => { + it('writes the rest of the file, leaves them out, and retries them next run', async () => { + const repo = createCatalogRepo() + const english = { greeting: 'Hello {name}', title: 'Title' } + repo.writeCatalog('en/main.json', english) + repo.writeText(manifestFile, json({ version: 1, files: {} })) + const corrupting = createTranslator((locale, item) => + `[${locale}] ${item.source}`.replace(' {name}', '') + ) + + const error = await repo.run(false, corrupting.translate).then( + () => undefined, + (rejection: unknown) => String(rejection) + ) + + expect(error).toContain('2 strings were rejected on every attempt') + expect(error).toContain('ja/main.json: main.json: greeting') + expect(repo.readCatalog('ja/main.json')).toEqual({ title: '[ja] Title' }) + expect(repo.readCatalog('zh-CN/main.json')).toEqual({ + title: '[zh-CN] Title' + }) + expect(repo.readManifest()).toEqual({ + version: 1, + files: { 'main.json': repo.blobId(english) } + }) + + const healthy = createTranslator() + expect((await repo.run(false, healthy.translate)).status).toBe(0) + expect(healthy.sourcesByLocale()).toEqual({ + ja: ['Hello {name}'], + 'zh-CN': ['Hello {name}'] + }) + }) +}) + describe('edits during generation', () => { it.for([ { file: 'en/main.json', edit: json({ title: 'Newer English' }) }, diff --git a/scripts/i18n/update-locales.test.ts b/scripts/i18n/update-locales.test.ts index 32dcf8bdbdc..905fb1b2838 100644 --- a/scripts/i18n/update-locales.test.ts +++ b/scripts/i18n/update-locales.test.ts @@ -55,15 +55,12 @@ async function updateLocaleFile( leafTokensDiffer ) const plan = buildTranslationItems('main.json', pendingLeaves) - const translations = - plan.items.length > 0 - ? await translateLocaleItems( - locale, - plan.items, - translateBatch, - translationConfig - ) - : new Map() + const { translated: translations } = await translateLocaleItems( + locale, + plan.items, + translateBatch, + translationConfig + ) const output = rebuildLocale( source, existing, diff --git a/scripts/i18n/update-locales.ts b/scripts/i18n/update-locales.ts index d04e884404f..1fe0352cfec 100644 --- a/scripts/i18n/update-locales.ts +++ b/scripts/i18n/update-locales.ts @@ -506,9 +506,36 @@ export async function updateLocales({ } type TranslationOutcome = - | { state: LocaleFileState; output: LocaleObject; known: string[] } + | { + state: LocaleFileState + output: LocaleObject + known: string[] + unfinished: string[] + } | { state: LocaleFileState; failure: string } +function withoutFailedLeaves( + pendingLeaves: readonly LocaleLeafEntry[], + translation: TranslationPlan, + failed: readonly TranslationItem[] +) { + const leafKeyOf = (item: TranslationItem) => + translation.refs.get(item.id)?.leafKey + const failedLeaves = new Set(failed.map(leafKeyOf)) + return { + failedLeaves: new Set([...failedLeaves].filter((key) => key !== undefined)), + pendingLeaves: pendingLeaves.filter( + (leaf) => !failedLeaves.has(pathKey(leaf.path)) + ), + translation: { + items: translation.items.filter( + (item) => !failedLeaves.has(leafKeyOf(item)) + ), + refs: translation.refs + } + } +} + async function translateStates( states: readonly LocaleFileState[], config: TranslationPipelineConfig, @@ -577,19 +604,22 @@ async function translateStates( config.localeFileConcurrency, async ({ state, translation }): Promise => { try { - const translated = translation.items.length - ? await translateLocaleItems( - state.locale, - translation.items, - translator, - config - ) - : new Map() + const { translated, failed } = await translateLocaleItems( + state.locale, + translation.items, + translator, + config + ) + const finished = withoutFailedLeaves( + state.pendingLeaves, + translation, + failed + ) const values = new Map([ ...state.retained, ...assembleLeafTranslations( - state.pendingLeaves, - translation, + finished.pendingLeaves, + finished.translation, translated ) ]) @@ -598,12 +628,17 @@ async function translateStates( state.existing, state.plan.invalidated, values, - state.omitted + new Set([...state.omitted, ...finished.failedLeaves]) ) const audit = auditState(state, output, config, 'output') if (audit.unexpected.length) throw new Error(audit.unexpected.map(formatTokenViolation).join('\n')) - return { state, output, known: audit.known } + return { + state, + output, + known: audit.known, + unfinished: failed.map(({ context }) => context) + } } catch (error) { return { state, @@ -678,10 +713,16 @@ function writeOutcomes({ serializeManifest({ version: 1, files, knownViolations }) ) const written = writeCatalogUpdates(updates, inputs) - if (failures.length) - throw new Error( - `Translation failed for ${failures.length} locale files:\n${failures.map(({ state, failure }) => `${state.label}: ${failure}`).join('\n')}\nAll locale results for ${[...failedFiles].join(', ')} were discarded together. Other entry files were written and recorded in the manifest.` - ) + const unfinished = completed.flatMap(({ state, unfinished }) => + unfinished.map((context) => `${state.label}: ${context}`) + ) + const problems = [ + failures.length && + `Translation failed for ${failures.length} locale files:\n${failures.map(({ state, failure }) => `${state.label}: ${failure}`).join('\n')}\nAll locale results for ${[...failedFiles].join(', ')} were discarded together. Other entry files were written and recorded in the manifest.`, + unfinished.length && + `${unfinished.length} strings were rejected on every attempt and left out; they render in English and retry on the next run:\n${unfinished.join('\n')}` + ].filter(Boolean) + if (problems.length) throw new Error(problems.join('\n')) return written } diff --git a/src/locales/CONTRIBUTING.md b/src/locales/CONTRIBUTING.md index d226ad02a83..b346e02ac8c 100644 --- a/src/locales/CONTRIBUTING.md +++ b/src/locales/CONTRIBUTING.md @@ -118,7 +118,9 @@ translations whose placeholders no longer match the English source are re-queued for translation, so corrupted strings heal on the next run. Results persist per entry file: a failure translating one file does not discard the completed, validated work of the others — those are written and their manifest -entries advance, and only the failed files retry on the next run. Runs that +entries advance, and only the failed files retry on the next run. Within a +file, a string still rejected after every retry is left out (English fallback) +and retried on the next run, while the rest of the file is written. Runs that prune keys report each affected file's exact deleted-key count. The release PR diff and review approve those deletions; there is no separate size-based bypass. Source-manifest, translation, and protected-token integrity failures remain hard From a73636947ee171472baefa16e4c96804fe9833b0 Mon Sep 17 00:00:00 2001 From: Benjamin Lu Date: Wed, 14 Oct 2026 14:29:12 -0700 Subject: [PATCH 2/4] ci(website): open the translation PR with git and gh Drop the third-party create-pull-request action. The workflow force-pushes the regenerated branch and opens a PR with the preinstalled gh CLI only when none is open. --- .github/workflows/i18n-update-website.yaml | 48 +++++++++++----------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/.github/workflows/i18n-update-website.yaml b/.github/workflows/i18n-update-website.yaml index c92cb52a4e6..50733ba9a26 100644 --- a/.github/workflows/i18n-update-website.yaml +++ b/.github/workflows/i18n-update-website.yaml @@ -43,43 +43,41 @@ jobs: env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} - - name: Open the translation PR - if: github.ref_name == 'main' - uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 - with: - token: ${{ secrets.PR_GH_TOKEN }} - branch: i18n/website-locales - add-paths: apps/website/src/locales/ - commit-message: 'fix(website): update locale catalogs' - title: 'fix(website): update locale catalogs' - labels: area:i18n - assignees: benceruleanlu - body: | - ## Summary - - Translations of new or changed English website copy, generated by [this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}). - - Every run regenerates this branch from main, so merge it before editing a translation by hand. - - name: Commit updated locales id: commit - if: github.ref_name != 'main' run: | git add apps/website/src/locales/ if git diff --cached --quiet; then exit 0; fi ./scripts/cicd/check-json.sh git -c user.name=github-actions -c user.email=github-actions@github.com \ - commit -m 'Update website locales' + commit -m 'fix(website): update locale catalogs' echo "committed=true" >> "$GITHUB_OUTPUT" - - name: Push updated locales + - name: Publish updated locales if: steps.commit.outputs.committed == 'true' env: - TARGET_BRANCH: ${{ github.ref_name }} - PR_GH_TOKEN: ${{ secrets.PR_GH_TOKEN }} + GH_TOKEN: ${{ secrets.PR_GH_TOKEN }} + SOURCE_BRANCH: ${{ github.ref_name }} + TRANSLATION_BRANCH: i18n/website-locales + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} run: | - git push "https://x-access-token:${PR_GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \ - "HEAD:refs/heads/$TARGET_BRANCH" + set -euo pipefail + remote="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + if [ "$SOURCE_BRANCH" != main ]; then + git push "$remote" "HEAD:refs/heads/$SOURCE_BRANCH" + exit 0 + fi + git push --force "$remote" "HEAD:refs/heads/$TRANSLATION_BRANCH" + open_pr=$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$TRANSLATION_BRANCH" \ + --state open --json url --jq '.[0].url // empty') + if [ -n "$open_pr" ]; then + echo "Updated $open_pr" + exit 0 + fi + body=$(printf '## Summary\n\nTranslations of new or changed English website copy, generated by [this workflow run](%s).\n\nEvery run regenerates this branch from main, so merge it before editing a translation by hand.\n' "$RUN_URL") + gh pr create --repo "$GITHUB_REPOSITORY" --base main --head "$TRANSLATION_BRANCH" \ + --title 'fix(website): update locale catalogs' --body "$body" \ + --label area:i18n --assignee benceruleanlu - name: Fail if some strings were not translated if: steps.translate.outcome == 'failure' From 67c001e9a476c366e51ffec10440fb83bf0736ba Mon Sep 17 00:00:00 2001 From: Benjamin Lu Date: Wed, 14 Oct 2026 15:12:22 -0700 Subject: [PATCH 3/4] refactor(i18n): describe locale failures outside writeOutcomes Splits the failure summaries out so writeOutcomes stays under the fallow complexity gate, and stops the website workflow's final step from claiming results were published when the translate step failed before writing any. --- .github/workflows/i18n-update-website.yaml | 4 +-- scripts/i18n/update-locales.ts | 39 +++++++++++++++++----- 2 files changed, 33 insertions(+), 10 deletions(-) diff --git a/.github/workflows/i18n-update-website.yaml b/.github/workflows/i18n-update-website.yaml index 50733ba9a26..8cffaab19a2 100644 --- a/.github/workflows/i18n-update-website.yaml +++ b/.github/workflows/i18n-update-website.yaml @@ -79,8 +79,8 @@ jobs: --title 'fix(website): update locale catalogs' --body "$body" \ --label area:i18n --assignee benceruleanlu - - name: Fail if some strings were not translated + - name: Fail if translation did not finish if: steps.translate.outcome == 'failure' run: | - echo "::error::Some website strings were not translated; the Update translations step lists them. Everything else was published, and the rest retry on the next run." + echo "::error::Website translation did not finish; the Update translations step lists what failed. It retries on the next run." exit 1 diff --git a/scripts/i18n/update-locales.ts b/scripts/i18n/update-locales.ts index 1fe0352cfec..e18ef3e14e7 100644 --- a/scripts/i18n/update-locales.ts +++ b/scripts/i18n/update-locales.ts @@ -514,6 +514,9 @@ type TranslationOutcome = } | { state: LocaleFileState; failure: string } +type CompletedOutcome = Extract +type FailedOutcome = Extract + function withoutFailedLeaves( pendingLeaves: readonly LocaleLeafEntry[], translation: TranslationPlan, @@ -713,19 +716,39 @@ function writeOutcomes({ serializeManifest({ version: 1, files, knownViolations }) ) const written = writeCatalogUpdates(updates, inputs) - const unfinished = completed.flatMap(({ state, unfinished }) => - unfinished.map((context) => `${state.label}: ${context}`) - ) const problems = [ - failures.length && - `Translation failed for ${failures.length} locale files:\n${failures.map(({ state, failure }) => `${state.label}: ${failure}`).join('\n')}\nAll locale results for ${[...failedFiles].join(', ')} were discarded together. Other entry files were written and recorded in the manifest.`, - unfinished.length && - `${unfinished.length} strings were rejected on every attempt and left out; they render in English and retry on the next run:\n${unfinished.join('\n')}` - ].filter(Boolean) + ...describeFailedFiles(failures, failedFiles), + ...describeUnfinishedStrings(completed) + ] if (problems.length) throw new Error(problems.join('\n')) return written } +function describeFailedFiles( + failures: readonly FailedOutcome[], + failedFiles: ReadonlySet +): string[] { + if (!failures.length) return [] + const details = failures + .map(({ state, failure }) => `${state.label}: ${failure}`) + .join('\n') + return [ + `Translation failed for ${failures.length} locale files:\n${details}\nAll locale results for ${[...failedFiles].join(', ')} were discarded together. Other entry files were written and recorded in the manifest.` + ] +} + +function describeUnfinishedStrings( + completed: readonly CompletedOutcome[] +): string[] { + const unfinished = completed.flatMap(({ state, unfinished }) => + unfinished.map((context) => `${state.label}: ${context}`) + ) + if (!unfinished.length) return [] + return [ + `${unfinished.length} strings were rejected on every attempt and left out; they render in English and retry on the next run:\n${unfinished.join('\n')}` + ] +} + function writeCatalogUpdates( updates: ReadonlyMap, inputs: ReadonlyMap From 61310787613c02108bde3c5201bfd454e6037b25 Mon Sep 17 00:00:00 2001 From: Benjamin Lu Date: Wed, 14 Oct 2026 16:54:59 -0700 Subject: [PATCH 4/4] ci(website): build on the open translation PR While the translation PR is open, each run merges main into its branch and translates only what changed, instead of re-translating every pending string and force-pushing a new SHA daily. Hand edits on the branch survive; a branch that conflicts with main is regenerated from it. A run with nothing left to translate closes the open PR. The PR lookup now filters by owner, so a fork branch with the same name cannot stand in for it. Changes to scripts/i18n/config.ts also trigger a run. Strings with no valid translation after every round are now reported as such, since provider deferrals take the same path as model rejections. Leaves with a missing translation are skipped inside assembleLeafTranslations, replacing withoutFailedLeaves. The English-only rule now exempts the hand-maintained excluded legal namespaces. Tests cover a stale translation whose English changed, an array leaf, and one locale rejecting while the other succeeds, and pin the partial result of translateLocaleItems. --- .github/workflows/i18n-update-website.yaml | 57 +++++++-- apps/website/AGENTS.md | 5 +- apps/website/README.md | 21 ++-- apps/website/src/config/translation.ts | 2 +- scripts/i18n/translate.test.ts | 55 +++++---- scripts/i18n/translate.ts | 7 +- .../i18n/update-locales.integration.test.ts | 114 +++++++++--------- scripts/i18n/update-locales.test.ts | 4 +- scripts/i18n/update-locales.ts | 68 ++++------- src/locales/CONTRIBUTING.md | 3 +- 10 files changed, 182 insertions(+), 154 deletions(-) diff --git a/.github/workflows/i18n-update-website.yaml b/.github/workflows/i18n-update-website.yaml index 8cffaab19a2..22569f43290 100644 --- a/.github/workflows/i18n-update-website.yaml +++ b/.github/workflows/i18n-update-website.yaml @@ -8,12 +8,14 @@ on: - 'apps/website/src/locales/en/*.json' - 'apps/website/src/config/locales.ts' - 'apps/website/src/config/translation.ts' + - 'scripts/i18n/config.ts' schedule: - cron: '17 10 * * *' workflow_dispatch: permissions: contents: read + pull-requests: read concurrency: group: i18n-update-website-${{ github.ref }} @@ -36,6 +38,28 @@ jobs: - name: Setup ComfyUI Frontend uses: ./.github/actions/setup-frontend + - name: Build on the open translation PR + id: base + if: github.ref_name == 'main' + env: + GH_TOKEN: ${{ github.token }} + TRANSLATION_BRANCH: i18n/website-locales + run: | + set -euo pipefail + echo "main_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT" + open_pr=$(gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$GITHUB_REPOSITORY_OWNER:$TRANSLATION_BRANCH" \ + --jq '.[0].html_url // empty') + echo "open_pr=$open_pr" >> "$GITHUB_OUTPUT" + if [ -z "$open_pr" ]; then exit 0; fi + git fetch --no-tags origin "refs/heads/$TRANSLATION_BRANCH" + echo "branch_sha=$(git rev-parse FETCH_HEAD)" >> "$GITHUB_OUTPUT" + if git -c user.name=github-actions -c user.email=github-actions@github.com \ + merge --no-edit FETCH_HEAD; then + echo "merged=true" >> "$GITHUB_OUTPUT" + else + git merge --abort + fi + - name: Update translations id: translate continue-on-error: true @@ -54,11 +78,16 @@ jobs: echo "committed=true" >> "$GITHUB_OUTPUT" - name: Publish updated locales - if: steps.commit.outputs.committed == 'true' + if: steps.commit.outputs.committed == 'true' || github.ref_name == 'main' env: GH_TOKEN: ${{ secrets.PR_GH_TOKEN }} SOURCE_BRANCH: ${{ github.ref_name }} TRANSLATION_BRANCH: i18n/website-locales + COMMITTED: ${{ steps.commit.outputs.committed }} + MAIN_SHA: ${{ steps.base.outputs.main_sha }} + OPEN_PR: ${{ steps.base.outputs.open_pr }} + BRANCH_SHA: ${{ steps.base.outputs.branch_sha }} + MERGED: ${{ steps.base.outputs.merged }} RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} run: | set -euo pipefail @@ -67,14 +96,26 @@ jobs: git push "$remote" "HEAD:refs/heads/$SOURCE_BRANCH" exit 0 fi - git push --force "$remote" "HEAD:refs/heads/$TRANSLATION_BRANCH" - open_pr=$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$TRANSLATION_BRANCH" \ - --state open --json url --jq '.[0].url // empty') - if [ -n "$open_pr" ]; then - echo "Updated $open_pr" + if git diff --quiet "$MAIN_SHA" HEAD; then + if [ -n "$OPEN_PR" ]; then + gh pr close "$OPEN_PR" --delete-branch --comment 'Main already has every translation on this branch.' + fi + exit 0 + fi + if [ "$COMMITTED" != true ] && [ "$MERGED" = true ]; then + echo "No new translations for $OPEN_PR" + exit 0 + fi + lease=--force + if [ -n "$BRANCH_SHA" ]; then + lease="--force-with-lease=refs/heads/$TRANSLATION_BRANCH:$BRANCH_SHA" + fi + git push "$lease" "$remote" "HEAD:refs/heads/$TRANSLATION_BRANCH" + if [ -n "$OPEN_PR" ]; then + echo "Updated $OPEN_PR" exit 0 fi - body=$(printf '## Summary\n\nTranslations of new or changed English website copy, generated by [this workflow run](%s).\n\nEvery run regenerates this branch from main, so merge it before editing a translation by hand.\n' "$RUN_URL") + body=$(printf '## Summary\n\nTranslations of new or changed English website copy, generated by [this workflow run](%s).\n\nLater runs merge main into this branch and translate only what changed, so translations edited here are kept.\n' "$RUN_URL") gh pr create --repo "$GITHUB_REPOSITORY" --base main --head "$TRANSLATION_BRANCH" \ --title 'fix(website): update locale catalogs' --body "$body" \ --label area:i18n --assignee benceruleanlu @@ -82,5 +123,5 @@ jobs: - name: Fail if translation did not finish if: steps.translate.outcome == 'failure' run: | - echo "::error::Website translation did not finish; the Update translations step lists what failed. It retries on the next run." + echo "::error::Website translation did not finish; the Update translations step lists what failed." exit 1 diff --git a/apps/website/AGENTS.md b/apps/website/AGENTS.md index ca7006aba98..20023d6cc7a 100644 --- a/apps/website/AGENTS.md +++ b/apps/website/AGENTS.md @@ -37,8 +37,9 @@ file wins. These root rules do not apply here: the request-bound `Astro.locals.t` in Astro or `translationsFor(locale).t` in Vue and TypeScript; never fill a placeholder with `.replace`. Write a literal `@`, `|`, `{` or `}` as `{'@'}`, `{'|'}`, `{'{'}` or `{'}'}`. Write new and - changed copy in `en/main.json` only and never edit another locale's file: a - workflow translates English changes on main into a PR, and missing strings + changed copy in `en/main.json` only. Do not edit another locale's file except + for the excluded legal namespaces in `src/config/translation.ts`: a workflow + translates eligible English changes on main into a PR, and missing strings render in English until it merges. See the README's Localization section. - The dev server is `pnpm --filter @comfyorg/website dev` on `http://localhost:4321`, not `pnpm dev` on 5173. The root diff --git a/apps/website/README.md b/apps/website/README.md index aa9b92bf6a3..d4f4ed66044 100644 --- a/apps/website/README.md +++ b/apps/website/README.md @@ -59,8 +59,9 @@ back to English. The catalog test compiles every message in every locale. nested feature key. Write new and changed copy in the English catalog only. Do not add or edit -other locales by hand: the generation workflow below translates it after it -merges, and until then those strings render in English. +eligible copy in other locales by hand: the generation workflow below +translates it after it merges, and until then those strings render in English. +People maintain the excluded namespaces listed below. Catalog files use two-space JSON indentation and a final newline. Legal and content pages render their sections in the order they appear in the catalog, so keep `en/main.json` in document order and never sort its keys. @@ -101,11 +102,11 @@ have no `/ja/` route yet. Generation never enables routes or indexing. The `i18n: Update Website` workflow runs when English catalogs or translation config change on main, and daily. It opens or updates one `fix(website): update locale catalogs` PR from the `i18n/website-locales` -branch. Each run regenerates that branch from main, so merge the PR before -editing its translations by hand. A string the model keeps getting wrong is -left out, so it renders in English, and is retried on the next run; the rest -of the file is still written. Running the workflow by hand on another branch -commits the translations to that branch instead. +branch. While that PR is open, each run merges main into the branch and +translates only what changed, so translations edited on the branch are kept. +When the branch conflicts with main, the run regenerates it from main instead. +Running the workflow by hand on another branch commits the translations to that +branch instead. Inside this package, run `pnpm locale:check` for an offline preflight, or `pnpm locale` with `OPENAI_API_KEY` to translate eligible missing or changed @@ -122,8 +123,10 @@ protected-token violations as JSON-encoded key paths, such as `["cloud","reason","1","title"]`. Use a clone with full history: if the recorded blob is missing, `locale:check` warns and skips change detection and token validation for that file, and `pnpm locale` fails. When a translation request -for an entry file fails, its English, locale catalogs and manifest entry keep -their previous contents. +for an entry file throws, such as an HTTP or network error, its English, locale +catalogs and manifest entry keep their previous contents. Strings the provider +defers or the model keeps getting wrong are left out and retried on the next +run. Commit the generated English catalog, locale catalogs and manifest together. If you edit any of them after generation, run `pnpm locale` again before diff --git a/apps/website/src/config/translation.ts b/apps/website/src/config/translation.ts index 40dcdd058ca..9e7db5c8c2b 100644 --- a/apps/website/src/config/translation.ts +++ b/apps/website/src/config/translation.ts @@ -12,7 +12,7 @@ const languages = { { name: string; guidance?: string } > -export const translationExclusions = [ +const translationExclusions = [ 'tos', 'enterprise-msa', 'privacy', diff --git a/scripts/i18n/translate.test.ts b/scripts/i18n/translate.test.ts index 2899582dcb9..d93ecb3110e 100644 --- a/scripts/i18n/translate.test.ts +++ b/scripts/i18n/translate.test.ts @@ -53,29 +53,37 @@ describe('translateLocaleItems', () => { ) ) } - const { translated: translations } = await translateLocaleItems( + const { translated } = await translateLocaleItems( locale, items, flaky, translationConfig ) - expect(translations.get('1')).toBe('Bonjour {name}') + expect(translated.get('1')).toBe('Bonjour {name}') expect(calls).toBe(2) }) - it('reports items still corrupted after the last round as failed', async () => { - const corrupting: TranslateBatch = (_batchLocale, batch) => + it('keeps passing translations and reports items still corrupted after the last round', async () => { + const corruptingGreeting: TranslateBatch = (_batchLocale, batch) => Promise.resolve( - Object.fromEntries(batch.map((item) => [item.id, 'Bonjour name'])) + Object.fromEntries( + batch.map((item) => [ + item.id, + item.id === '1' ? 'Bonjour name' : 'Titre' + ]) + ) ) - const { translated, failed } = await translateLocaleItems( + const { translated, untranslated } = await translateLocaleItems( locale, - items, - corrupting, + [ + ...items, + { id: '2', context: 'main.json: title', source: 'Title', preserve: [] } + ], + corruptingGreeting, translationConfig ) - expect(translated.size).toBe(0) - expect(failed.map(({ context }) => context)).toEqual([ + expect(translated).toEqual(new Map([['2', 'Titre']])) + expect(untranslated.map(({ context }) => context)).toEqual([ 'main.json: greeting' ]) }) @@ -90,13 +98,13 @@ describe('translateLocaleItems', () => { ) ) } - const { translated: translations } = await translateLocaleItems( + const { translated } = await translateLocaleItems( locale, items, blankFirst, translationConfig ) - expect(translations.get('1')).toBe('Bonjour {name}') + expect(translated.get('1')).toBe('Bonjour {name}') expect(calls).toBe(2) }) @@ -118,16 +126,11 @@ describe('translateLocaleItems', () => { inFlight-- return Object.fromEntries(batch.map((item) => [item.id, `t${item.id}`])) } - const { translated: translations } = await translateLocaleItems( - locale, - sixItems, - gated, - { - ...translationConfig, - requestConcurrency: 2 - } - ) - expect(translations.size).toBe(6) + const { translated } = await translateLocaleItems(locale, sixItems, gated, { + ...translationConfig, + requestConcurrency: 2 + }) + expect(translated.size).toBe(6) expect(maxInFlight).toBe(2) }) @@ -146,13 +149,13 @@ describe('translateLocaleItems', () => { let call = 0 const crossTalking: TranslateBatch = () => Promise.resolve(responses[call++] ?? {}) - const { translated: translations } = await translateLocaleItems( + const { translated } = await translateLocaleItems( locale, threeItems, crossTalking, translationConfig ) - expect(translations.get('3')).toBe('ok3') + expect(translated.get('3')).toBe('ok3') }) it('sends a retry note naming the violation on later rounds', async () => { @@ -205,7 +208,7 @@ describe('translateLocaleItems', () => { ) } - const { translated: translations } = await translateLocaleItems( + const { translated } = await translateLocaleItems( locale, [docsLink], correctsOnRetry, @@ -218,7 +221,7 @@ describe('translateLocaleItems', () => { } ) - expect(translations).toEqual(new Map([['1', accepted]])) + expect(translated).toEqual(new Map([['1', accepted]])) expect(requests).toEqual([[docsLink], [{ ...docsLink, retryNote }]]) } ) diff --git a/scripts/i18n/translate.ts b/scripts/i18n/translate.ts index 6584edf1c1b..96e564491f7 100644 --- a/scripts/i18n/translate.ts +++ b/scripts/i18n/translate.ts @@ -391,7 +391,10 @@ export async function translateLocaleItems( | 'maxTranslationRounds' | 'strictProtectedTokens' > -): Promise<{ translated: Map; failed: TranslationItem[] }> { +): Promise<{ + translated: Map + untranslated: TranslationItem[] +}> { const translated = new Map() let remaining = [...items] @@ -439,5 +442,5 @@ export async function translateLocaleItems( remaining = failed } - return { translated, failed: remaining } + return { translated, untranslated: remaining } } diff --git a/scripts/i18n/update-locales.integration.test.ts b/scripts/i18n/update-locales.integration.test.ts index 1692e9f2d29..aca6b2ba38d 100644 --- a/scripts/i18n/update-locales.integration.test.ts +++ b/scripts/i18n/update-locales.integration.test.ts @@ -386,76 +386,75 @@ describe('failure isolation', () => { const aFiles = ['en/a.json', 'ja/a.json', 'zh-CN/a.json'] - it.for([ - { - label: 'the provider fails', - translator: () => - createTranslator( - undefined, - (locale, item) => - locale === 'zh-CN' && item.context.startsWith('a.json:') - ), - failures: ['zh-CN/a.json: provider unavailable'] - } - ])( - 'discards one entry file when $label while another file is written', - async ({ translator, failures }) => { - const repo = createTwoFileRepo() - const before = repo.readTree() - const recordedA = repo.blobId({ alpha: 'Alpha' }) + it('discards one entry file when the provider fails while another file is written', async () => { + const repo = createTwoFileRepo() + const before = repo.readTree() + const recordedA = repo.blobId({ alpha: 'Alpha' }) + const failingZhA = createTranslator( + undefined, + (locale, item) => locale === 'zh-CN' && item.context.startsWith('a.json:') + ) - const error = await repo.run(false, translator().translate).then( - () => undefined, - (rejection: unknown) => String(rejection) - ) + const error = await repo.run(false, failingZhA.translate).then( + () => undefined, + (rejection: unknown) => String(rejection) + ) - expect(error).toContain(`Translation failed for ${failures.length}`) - expect(error?.split('\n')).toEqual( - expect.arrayContaining( - failures.map((failure) => expect.stringContaining(failure)) - ) - ) - const after = repo.readTree() - expect(aFiles.map((file) => after[file])).toEqual( - aFiles.map((file) => before[file]) - ) - expect(after['ja/b.json']).toBe( - json({ delta: '[ja] Delta', gamma: 'ガンマ' }) - ) - expect(after['zh-CN/b.json']).toBe( - json({ delta: '[zh-CN] Delta', gamma: '伽马' }) - ) - expect(repo.readManifest()).toEqual({ - version: 1, - files: { - 'a.json': recordedA, - 'b.json': repo.blobId({ delta: 'Delta', gamma: 'Gamma' }) - }, - knownViolations: { 'a.json': ['["alpha"]'] } - }) - } - ) + expect(error).toContain( + 'Translation failed for 1 locale files:\nzh-CN/a.json: provider unavailable' + ) + const after = repo.readTree() + expect(aFiles.map((file) => after[file])).toEqual( + aFiles.map((file) => before[file]) + ) + expect(after['ja/b.json']).toBe( + json({ delta: '[ja] Delta', gamma: 'ガンマ' }) + ) + expect(after['zh-CN/b.json']).toBe( + json({ delta: '[zh-CN] Delta', gamma: '伽马' }) + ) + expect(repo.readManifest()).toEqual({ + version: 1, + files: { + 'a.json': recordedA, + 'b.json': repo.blobId({ delta: 'Delta', gamma: 'Gamma' }) + }, + knownViolations: { 'a.json': ['["alpha"]'] } + }) + }) }) -describe('strings rejected on every attempt', () => { - it('writes the rest of the file, leaves them out, and retries them next run', async () => { +describe('strings with no valid translation after every attempt', () => { + it('leaves out strings one locale rejects and retries only those next run', async () => { const repo = createCatalogRepo() - const english = { greeting: 'Hello {name}', title: 'Title' } + repo.recordEnglish({ 'main.json': { greeting: 'Hi {name}' } }) + const english = { + greeting: 'Hello {name}', + steps: ['Step {name}', 'Plain'], + title: 'Title' + } repo.writeCatalog('en/main.json', english) - repo.writeText(manifestFile, json({ version: 1, files: {} })) - const corrupting = createTranslator((locale, item) => - `[${locale}] ${item.source}`.replace(' {name}', '') + repo.writeCatalog('ja/main.json', { greeting: 'やあ {name}' }) + repo.writeCatalog('zh-CN/main.json', { greeting: '嗨 {name}' }) + const corruptingJapanese = createTranslator((locale, item) => + locale === 'ja' + ? `[ja] ${item.source}`.replace(' {name}', '') + : `[${locale}] ${item.source}` ) - const error = await repo.run(false, corrupting.translate).then( + const error = await repo.run(false, corruptingJapanese.translate).then( () => undefined, (rejection: unknown) => String(rejection) ) - expect(error).toContain('2 strings were rejected on every attempt') - expect(error).toContain('ja/main.json: main.json: greeting') + expect(error).toContain( + '2 strings had no valid translation after every attempt' + ) + expect(error).toContain('ja/main.json: main.json: steps[0]') expect(repo.readCatalog('ja/main.json')).toEqual({ title: '[ja] Title' }) expect(repo.readCatalog('zh-CN/main.json')).toEqual({ + greeting: '[zh-CN] Hello {name}', + steps: ['[zh-CN] Step {name}', '[zh-CN] Plain'], title: '[zh-CN] Title' }) expect(repo.readManifest()).toEqual({ @@ -466,8 +465,7 @@ describe('strings rejected on every attempt', () => { const healthy = createTranslator() expect((await repo.run(false, healthy.translate)).status).toBe(0) expect(healthy.sourcesByLocale()).toEqual({ - ja: ['Hello {name}'], - 'zh-CN': ['Hello {name}'] + ja: ['Hello {name}', 'Step {name}', 'Plain'] }) }) }) diff --git a/scripts/i18n/update-locales.test.ts b/scripts/i18n/update-locales.test.ts index 905fb1b2838..7482bdad751 100644 --- a/scripts/i18n/update-locales.test.ts +++ b/scripts/i18n/update-locales.test.ts @@ -55,7 +55,7 @@ async function updateLocaleFile( leafTokensDiffer ) const plan = buildTranslationItems('main.json', pendingLeaves) - const { translated: translations } = await translateLocaleItems( + const { translated } = await translateLocaleItems( locale, plan.items, translateBatch, @@ -65,7 +65,7 @@ async function updateLocaleFile( source, existing, invalidated, - assembleLeafTranslations(pendingLeaves, plan, translations) + assembleLeafTranslations(pendingLeaves, plan, translated) ) return { output, translatedCount: plan.items.length } } diff --git a/scripts/i18n/update-locales.ts b/scripts/i18n/update-locales.ts index e18ef3e14e7..c5e9f8ece02 100644 --- a/scripts/i18n/update-locales.ts +++ b/scripts/i18n/update-locales.ts @@ -133,11 +133,15 @@ export function assembleLeafTranslations( structuredClone(leaf.value) ]) ) + const untranslated = new Set() for (const item of plan.items) { const ref = plan.refs.get(item.id) + if (!ref) throw new Error(`Missing reference for item ${item.context}`) const translated = translations.get(item.id) - if (!ref || translated === undefined) - throw new Error(`Missing translation for item ${item.context}`) + if (translated === undefined) { + untranslated.add(ref.leafKey) + continue + } const leaf = assembled.get(ref.leafKey) if (leaf === undefined) throw new Error(`Unknown leaf for ${item.context}`) if (ref.indices.length === 0) { @@ -155,6 +159,7 @@ export function assembleLeafTranslations( } container[ref.indices.at(-1) ?? 0] = translated } + for (const key of untranslated) assembled.delete(key) return assembled } @@ -510,35 +515,13 @@ type TranslationOutcome = state: LocaleFileState output: LocaleObject known: string[] - unfinished: string[] + untranslated: string[] } | { state: LocaleFileState; failure: string } type CompletedOutcome = Extract type FailedOutcome = Extract -function withoutFailedLeaves( - pendingLeaves: readonly LocaleLeafEntry[], - translation: TranslationPlan, - failed: readonly TranslationItem[] -) { - const leafKeyOf = (item: TranslationItem) => - translation.refs.get(item.id)?.leafKey - const failedLeaves = new Set(failed.map(leafKeyOf)) - return { - failedLeaves: new Set([...failedLeaves].filter((key) => key !== undefined)), - pendingLeaves: pendingLeaves.filter( - (leaf) => !failedLeaves.has(pathKey(leaf.path)) - ), - translation: { - items: translation.items.filter( - (item) => !failedLeaves.has(leafKeyOf(item)) - ), - refs: translation.refs - } - } -} - async function translateStates( states: readonly LocaleFileState[], config: TranslationPipelineConfig, @@ -607,31 +590,26 @@ async function translateStates( config.localeFileConcurrency, async ({ state, translation }): Promise => { try { - const { translated, failed } = await translateLocaleItems( + const { translated, untranslated } = await translateLocaleItems( state.locale, translation.items, translator, config ) - const finished = withoutFailedLeaves( + const assembled = assembleLeafTranslations( state.pendingLeaves, translation, - failed + translated ) - const values = new Map([ - ...state.retained, - ...assembleLeafTranslations( - finished.pendingLeaves, - finished.translation, - translated - ) - ]) + const unassembled = state.pendingLeaves + .map(({ path }) => pathKey(path)) + .filter((key) => !assembled.has(key)) const output = rebuildLocale( state.plan.source, state.existing, state.plan.invalidated, - values, - new Set([...state.omitted, ...finished.failedLeaves]) + new Map([...state.retained, ...assembled]), + new Set([...state.omitted, ...unassembled]) ) const audit = auditState(state, output, config, 'output') if (audit.unexpected.length) @@ -640,7 +618,7 @@ async function translateStates( state, output, known: audit.known, - unfinished: failed.map(({ context }) => context) + untranslated: untranslated.map(({ context }) => context) } } catch (error) { return { @@ -718,7 +696,7 @@ function writeOutcomes({ const written = writeCatalogUpdates(updates, inputs) const problems = [ ...describeFailedFiles(failures, failedFiles), - ...describeUnfinishedStrings(completed) + ...describeUntranslatedStrings(completed) ] if (problems.length) throw new Error(problems.join('\n')) return written @@ -737,15 +715,15 @@ function describeFailedFiles( ] } -function describeUnfinishedStrings( +function describeUntranslatedStrings( completed: readonly CompletedOutcome[] ): string[] { - const unfinished = completed.flatMap(({ state, unfinished }) => - unfinished.map((context) => `${state.label}: ${context}`) + const untranslated = completed.flatMap(({ state, untranslated }) => + untranslated.map((context) => `${state.label}: ${context}`) ) - if (!unfinished.length) return [] + if (!untranslated.length) return [] return [ - `${unfinished.length} strings were rejected on every attempt and left out; they render in English and retry on the next run:\n${unfinished.join('\n')}` + `${untranslated.length} strings had no valid translation after every attempt and were left out; they render in English and retry on the next run:\n${untranslated.join('\n')}` ] } diff --git a/src/locales/CONTRIBUTING.md b/src/locales/CONTRIBUTING.md index b346e02ac8c..faa1435dda0 100644 --- a/src/locales/CONTRIBUTING.md +++ b/src/locales/CONTRIBUTING.md @@ -119,7 +119,8 @@ re-queued for translation, so corrupted strings heal on the next run. Results persist per entry file: a failure translating one file does not discard the completed, validated work of the others — those are written and their manifest entries advance, and only the failed files retry on the next run. Within a -file, a string still rejected after every retry is left out (English fallback) +file, a string with no valid translation after every round, whether the model +keeps corrupting it or the provider defers it, is left out (English fallback) and retried on the next run, while the rest of the file is written. Runs that prune keys report each affected file's exact deleted-key count. The release PR diff and review approve those deletions; there is no separate size-based bypass.