Skip to content

TRANSLATION_GUIDE.md

Latest commit

 

History

History
65 lines (45 loc) · 1.7 KB

TRANSLATION_GUIDE.md

File metadata and controls

65 lines (45 loc) · 1.7 KB

Translation Guide

This project uses a namespace-based i18n setup so contributors can localize safely without changing app logic.

Locale Files

All locale files live under:

  • src/i18n/locales/en/
  • src/i18n/locales/es/
  • src/i18n/locales/zh-CN/

Each locale has the same namespace files:

  • common.json
  • launch.json
  • editor.json
  • timeline.json
  • settings.json
  • dialogs.json
  • shortcuts.json

English (en) is the source of truth for key structure.

Key Rules

  • Keep the same key paths across locales.
  • Do not rename existing keys unless coordinated with code changes.
  • Add new keys to en first, then mirror into all other locales.
  • Prefer descriptive, stable keys. Example: app.editorTitle.
  • Interpolation is supported with {{name}} style placeholders.

How Translation Is Read

  • Keys with a namespace prefix like settings.export.title use that namespace.
  • Keys without a namespace default to common.
  • Missing translations fall back to English, then to the provided fallback string, then to the key.

Validate Locale Structure

Run:

npm run i18n:check

This checks for:

  • Missing namespace files
  • Missing keys compared to en
  • Extra keys not present in en

Contributor Workflow

  1. Pull latest main.
  2. Update en/<namespace>.json with new keys if needed.
  3. Add matching keys to other locale files.
  4. Run npm run i18n:check.
  5. Run app locally (npm run dev) and spot-check UI text.
  6. Open PR with a short summary of changed namespaces.

Scope Notes

Current framework is app-wide and ready for full localization rollout. Not every UI string is migrated yet. Migration should be done incrementally by namespace to keep PRs reviewable and low-risk.