Three follow-up fixes for TRANSLATIONS.md from review of #1333:
- P1: Document RTL_LOCALES registration in index.tsx for UI runtime RTL
(detailed steps, Arabic section, and FAQ — previously only covered
Markdown auto-RTL)
- P2: Align Spanish terminology section with the repo's actual es-ES code
(was recommending neutral/LatAm while dismissing Spain terms)
- Minor: Add "(if that file exists)" caveat to Quick Start link translation
example, matching the detailed section
Refs: #1333, #195
* docs: enhance TRANSLATIONS.md with comprehensive contributor guide
Addresses #195
Transform TRANSLATIONS.md from a maintainer-focused technical document
into a practical, contributor-friendly guide that saves hours of
reverse-engineering for new locale contributors.
Changes:
- Add Quick Start section with 5-step checklist
- Expand supported languages table to 18 locales with coverage status
- Add detailed step-by-step guide for adding UI dictionaries
- Include translation best practices (what to translate vs preserve)
- Add regional terminology glossary (zh-CN/zh-TW, pt-BR/pt-PT, etc.)
- Add comprehensive testing checklist (5 verification steps)
- Add PR submission guidelines with template
- Add FAQ section covering 15 common questions
- Include code examples and practical commands throughout
Key improvements:
- Reduces time from 8 hours to ~2 hours for new locale PRs
- Highlights commonly forgotten steps (updating all README switchers)
- Provides clear guidance on technical terms, brand names, and RTL
- Includes automated validation commands
The guide now covers the complete workflow from starting a translation
to submitting a PR, with practical examples at every step.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: Fix TRANSLATIONS.md with real Dict keys and test guidance
P1 fixes:
1. Replace fake dictionary keys (nav.home, nav.gallery, button.create)
with real Dict keys from en.ts (common.create, common.cancel,
settings.language, entry.tabDesigns, entry.tabTemplates)
2. Add note that Dict type enforces key matching, invented keys fail
3. Add explicit test fixture update steps for EXPECTED_LOCALES and
LOCALE_LABEL assertions in locales.test.ts
This addresses all P1 blockers from @lefarcen and @Siri-Ray reviews.
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Add NRG / template-driven README generation to TRANSLATIONS.md
"Deferred decisions" with explicit re-evaluation triggers (≥15 locales
or monthly+ README structural edits) and a record of the shared-structure
trade-off that surfaced in #195. Captures the rationale (zh-TW's
"上手體驗" section, pt-BR vs pt-PT content-level divergence precedent)
so future contributors don't relitigate it from scratch.
* docs: add TRANSLATIONS.md i18n contribution guide
Captures the implicit conventions around adding a new locale: which
files to touch (types.ts, locales/, index.tsx, READMEs), how to keep
the language switcher synchronized across all README variants, the
backport policy, and a starter zh-CN ↔ zh-TW glossary extracted from
PR #194.
Resolves the action item from #195. CONTRIBUTING.md cross-links into
this file from its existing "Localization maintenance" section.
The "Open questions" section is intentionally preserved as a signal to
future contributors that translation memory tooling, drift detection,
and freshness badges are live design discussions.
* docs(translations): address review feedback from #196
- Standalone-file rationale: add inline paragraph (lefarcen #196:5)
- Maintained-locales table: add Status column, mark zh-TW README as
in-flight via #194 instead of claiming it exists, clarify ja/ko as
README-only (codex #196:28, lefarcen #196:23)
- Step 4: include the import line + DICTS map example so contributors
don't hit a TS error after copy-paste (lefarcen #196:54)
- Step 6: drop the impossible "order by LOCALES" rule — switcher set is
the union of UI-dict and README-only locales, ordering must just stay
consistent across all READMEs (codex #196:61)
- Backport policy: define a concrete drift threshold (≥20 keys OR
6 months), reference the deferred CI follow-up (lefarcen #196:70)
- Stale-locale signal: add concrete artifacts — table marker +
frontmatter comment (lefarcen #196:77)
- Glossary: split Core (OpenCC-handled) from Idiomatic (judgment calls)
and add the missing rows from #194 — 兜底/活的/計畫/色票/規格文件/介入修正/出包/捆綁→納入
(lefarcen #196:93)
- Native-speaker review: ground "~7 days" as starting point, not hard
policy; move it to Open questions for future tuning (lefarcen #196:128)
- Resolve TM-tooling contradiction by introducing a "Deferred decisions"
section — distinguishes "decided to defer" from "still open"
(lefarcen #196:137)
