Add Japanese localization pipeline: NT-tag do-not-translate mechanism, translation scripts, and ja locale wiring

[zoltan-baba]

Summary

The Japanese localization pipeline: the scripts that generate the term glossary, tag protected terms in the docs source, and translate changed pages — plus the ja locale content and the locale switcher.

The infrastructure prep that used to live here has been split out and merged (#188, #189), and main is merged back in, so this branch is now purely additive: 19 files, +4,892 / −0, and up to date with main.

Pipeline

• .github/scripts/build_ui_library.py — scans the product frontends + steplib + docs, emits ui_copy_library.json and the tiered do-not-translate glossary.
• scripts/add_notranslate_tags.py — reads that glossary and wraps protected terms in <NT> directly in the .mdx source. Idempotent, and inserts its own import.
• .github/scripts/translate_docs.py — mask → translate → unmask. Masks whole <NT> spans, code, URLs, env vars, filenames and MDX syntax before the model sees the text. JTF house-style system prompt, plus a preferred-translations map for terms that are translated. Front matter is split off and never sent, so slug can't be touched. Auto-generated OpenAPI pages are excluded — they'd go stale on the next spec sync.
• Workflows: translate-ja-docs.yml (translate changed pages on docs PRs), refresh-ui-library.yml (weekly glossary regeneration + re-tag), ja-style-check.yml + .textlintrc.yaml (JTF textlint).

Locale content and switcher

• i18n/ja/ — theme strings (code.json, translated), sidebar labels (current.json, scaffolded but still English), and one fully translated pilot page.
• Navbar locale dropdown (docusaurus.config.ts) plus the navbar text colour it needs to be readable on the purple header (src/css/custom.css).

Docs

• localization/README.md and JA-TRANSLATION-GUIDE.md — how the pipeline fits together, with a LIVE/PROCESS/ROADMAP status legend.

Open issues — read before merging

All re-verified against the merged tree.

No <NT> tags are applied yet. The tagger has never been run against the tree: zero files under docs/ or src/partials/ contain a tag, while a dry run reports 17,140 wraps across 499 files. Until that pass lands, translate_docs.py has nothing to mask beyond code, URLs and ALL-CAPS runs — measured on one real page, 99 occurrences of unambiguous protected terms (Bitrise ×18, Workspace ×13, Workflow ×6, Release Management ×5, …) are fully exposed to the model. The glossary is not a fallback: it is the tagger's term source and is never read at translation time.

translate-ja-docs.yml runs on every docs PR and auto-commits, so merging before the tagging pass turns on unprotected translation immediately. Deciding where that pass lands is the one thing blocking this PR from being safe to merge.

translate_docs.py truncates silently. max_tokens=8000 with no stop_reason check (line 179). Seven pages exceed 20KB, the largest is 44KB. A truncated response is written to disk and committed by the workflow with no signal. No retry or error handling either.

ja-style-check.yml is a no-op — and its green check here is misleading. Verified: textlint exits 0 with no output on .mdx, silently skipping unsupported extensions, and every page is .mdx now. The same content as .md reports 2 errors, both Docusaurus :::note[title] syntax tripping JTF rule 4.3.2, so that rule needs disabling before MDX support is worth adding. It also has no continue-on-error, so despite being described as non-blocking it becomes a hard gate the moment it starts working.

The weekly refresh will drop glossary tiers. build_ui_library.py emits step_names:, but add_notranslate_tags.py reads step_names_and_field_labels — and the generator emits no code_literals at all, which the tagger also reads. refresh-ui-library.yml regenerates the glossary then re-runs the tagger and opens a PR, so the first scheduled run silently drops all 156 Step names and produces a mass-untagging PR that looks like a routine chore.

Stale comments in the glossary. Line 13 still says do_not_translate terms "are injected into the translation prompt as a hard rule", describing the design this PR replaced — reading the file top-down gives the wrong model of how protection works. The preferred_translations: {} stub at the bottom is also dead; ja-preferred-translations.yaml supersedes it.

Known gaps (by design, documented in JA-TRANSLATION-GUIDE.md)

• No translation memory / segment reuse yet — roadmap.
• Partials (src/partials/) aren't translated. They're inlined via JSX import, so a translated page still renders an English partial.
• Front matter isn't translated: title and description stay English, so JA pages show English titles in nav and English social preview cards.
• The JA sidebar tree is untranslated — current.json is scaffolded but still English, and nothing in the pipeline translates it.
• ja-preferred-translations.yaml seed values need a fluent Japanese reviewer before being treated as authoritative.
• static/_headers still noindexes /ja/*. Correct while one page of ~440 is translated, but main's commit 3444eb4 asks for the rule to be revisited here — worth an explicit decision and a drop criterion.

Test plan

• Full production build (npm run build) succeeds for both en and ja.
• One real page (bitrise-ci/getting-started/getting-started) translated through the full mask/translate/unmask pipeline and verified rendering in a served production build.
• Locale switching verified in a served production build (dev mode serves one locale at a time).
• main merged in; check-links-source, check-partials-source and check-generated-partials all clean on the merged tree.
• Decide whether the 17k-tag pass lands here, as its own PR, or via the first weekly refresh run.
• Fix the glossary tier-name mismatch before the first refresh-ui-library.yml run.

🤖 Generated with Claude Code

[github-actions]

Preview: https://ja-localization-full.bitrise-docs.pages.dev