Files
youtube-generator/docs/I18N.md
T
poli0981andClaude Opus 5.5 f472c1e760 docs: v1.3.0 — toolchain docs and changelog; bump to 1.3.0
- CHANGELOG v1.3.0; ROADMAP (v1.3.0 shipped, ES2026 next)
- DEVELOPMENT + vi: Node 26 / npm 11, TypeScript 7 with the 6.0 API alias,
  and the IDE setting that follows from it
- TECH-SPEC: package.json, tsconfig, the Vite target, toolchain notes
  (TypeScript aliases, Node 26 web storage, npm ci --ignore-scripts)
- PACKAGING: supported WebViews, Android cloud backups off, Node 26, the
  tauri.conf.json excerpt
- HOSTING, ARCHITECTURE, README (node >= 26, TypeScript 7), FEATURES, I18N,
  CONTENT-INVENTORY + vi, DISCLAIMER + vi, SECURITY (1.3.x), the bug-report
  template, CLAUDE.md (TypeScript 7, the browser-floor lib, linear regexes,
  SonarCloud, npm aliases)
- Six manifests bumped 1.2.0 -> 1.3.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 15:11:17 +07:00

15 KiB
Raw Blame History

Internationalization Guide (i18n)

YTDescGen — Adding & Managing Languages


Overview

YTDescGen has two independent language contexts:

  1. UI Language — the app interface (buttons, labels, tooltips). Stored as appLanguage in the settings store (src/store/settings-store.ts); changed from the top bar, Settings or the command palette. Affects how the app looks.
  2. Output Language — the generated title/description/tags. Stored as language in the editor store (src/store/editor-store.ts), per draft; a new draft starts in Settings › Default Output Language. Affects what the app produces. The Output page, Batch and Social can also render several output languages at once.

These are independent: a Vietnamese user can browse the app in Vietnamese (UI) while generating descriptions in Japanese (output). Both defaults follow the browser's language when it is one of the eight, otherwise English.

Locales (8)

Code Language Authoring
en English Source locale; the only one bundled in the main chunk
vi Vietnamese Reviewed by the maintainer, a native speaker
ja Japanese AI-translated, not native-reviewed
es Spanish AI-translated, not native-reviewed
ko Korean AI-translated, not native-reviewed
zh Chinese (Simplified) AI-translated, not native-reviewed
pt-BR Portuguese (Brazil) AI-translated, not native-reviewed
id Indonesian AI-translated, not native-reviewed

The authoring status of each locale is recorded in DISCLAIMER.md.

Two Namespaces

Namespace File Holds Rendered in
ui ui.json Everything the interface shows the UI language
templates templates.json Everything the engine writes: title patterns, description blocks, rig labels (description.rigLabels), timestamp keywords (timeline.keywords), pinned comments, playlist copy, hashtags the output language

Rule: generated text lives in templates.json. A sentence or label the engine writes into a title, description or caption is looked up in templates.json, in the output language, through the t the engine is given (i18n.getFixedT(language, "templates"), see src/hooks/use-generated-output.ts) — it is never typed into src/engine/. v1.0.0 moved the rig labels there (description.rigLabels.*); they used to print as English field names in every language.

What stays in code is per-language data that isn't a sentence:

  • the tag pools CORE_TAGS_BY_LANG and MULTILINGUAL_TAGS in src/engine/tag-generator.ts (search terms), and
  • the patterns in src/engine/channel-phrase.ts that remove the words going with an empty channel name ("on", "trên kênh", "による"…).

Both are typed Record<SupportedLanguage, …>, so a new language is a compile error until it has an entry — see Steps 5 and 6.

File Structure

src/i18n/
├── index.ts                # i18next init + SUPPORTED_LANGUAGES (en eager, others lazy-loaded)
└── locales/
    ├── _schema.json        # Every required key, per namespace
    ├── en/
    │   ├── ui.json          # UI strings (buttons, labels, errors, tooltips)
    │   └── templates.json   # Generated content (titles, description blocks, …)
    ├── vi/
    ├── ja/
    ├── es/
    ├── ko/
    ├── zh/
    ├── pt-BR/
    └── id/                  # Each with the same ui.json + templates.json

_schema.json lists, for each object path in each namespace, the keys it must contain — an excerpt:

{
  "ui": {
    "sidebar": ["expand", "collapse"]
  },
  "templates": {
    "title.separators": ["emDash", "hyphen", "colon", "pipe"]
  }
}

Adding or removing a key means editing _schema.json and all 8 locales.

Adding a New Language — Checklist

The examples use French (fr), one of the locales on the roadmap.

Step 1: Create locale files

# Generate empty locale from the English source
npm run generate:locale -- --lang fr

# This creates:
# src/i18n/locales/fr/ui.json        (all keys, empty values)
# src/i18n/locales/fr/templates.json (all keys, empty values)

# Prefer editing in place over working from blanks? Pre-fill with English:
npm run generate:locale -- --lang fr --copy-english

# Overwrite an existing locale directory:
npm run generate:locale -- --lang fr --force

The output is key-for-key identical to English, so npm run validate:locales passes the moment the files are written — it checks key parity, not whether the values were actually translated.

Or copy from English and translate:

cp -r src/i18n/locales/en src/i18n/locales/fr

Step 2: Translate ui.json

What a finished file looks like — an excerpt of src/i18n/locales/es/ui.json (locale files are plain JSON: no comments, no trailing commas):

{
  "tabs": {
    "editor": "Editor",
    "output": "Resultado",
    "profiles": "Perfiles",
    "history": "Historial",
    "settings": "Ajustes",
    "batch": "Lote",
    "social": "Redes",
    "playlist": "Playlist",
    "logs": "Registros",
    "about": "Acerca de",
    "reportBug": "Reportar bug"
  },
  "output": {
    "title": "Título",
    "description": "Descripción",
    "tags": "Etiquetas",
    "copyTitle": "Copiar Título",
    "copyAll": "Copiar Todo",
    "copied": "¡Copiado!",
    "charCount": "{{count}}/{{limit}}"
  }
}

Step 3: Translate templates.json

An excerpt of src/i18n/locales/es/templates.json:

{
  "title": {
    "separator": " — ",
    "suffix": "Gameplay No Commentary",
    "videoType": {
      "full": "",
      "part": "Parte {{partNumber}}",
      "boss": "{{bossName}} Pelea de Jefe",
      "dlc": "{{dlcName}} DLC"
    }
  },
  "description": {
    "intro": {
      "full": "Este video presenta el gameplay completo de {{gameName}} en {{channelName}}.",
      "part": "Este video presenta la Parte {{partNumber}} de {{gameName}} en {{channelName}}."
    },
    "noCommentaryLine": "Sin Comentarios — gameplay puro para tu disfrute.",
    "sections": {
      "timestamps": "⏱ MARCAS DE TIEMPO",
      "rig": "💻 MI EQUIPO",
      "cta": "👍 Me gusta | 🔔 Suscríbete | ↗️ Comparte"
    },
    "rigLabels": {
      "cpu": "CPU",
      "gpu": "GPU",
      "os": "Sistema Operativo"
    }
  },
  "timeline": {
    "keywords": {
      "chapter": "Capítulo {{n}}",
      "boss": "Jefe {{n}}",
      "final_boss": "Jefe Final",
      "credits": "Créditos"
    }
  }
}
  • Keep every {{variable}} exactly as it is; only the text around it is translated.
  • Sentences that name the channel ({{channelName}}) must still read naturally when the channel phrase is removed — see Step 5.
  • Don't use i18next plural suffixes (_one, _other, …). Languages need different plural forms, so the key sets would differ between locales and validate:locales would fail. Write count-neutral text instead ("{{n}} damaged item(s) skipped").

Step 4: Register the language

Registering a locale touches several files, and two of them fail silently if missed. tests/i18n/locale-registration.test.ts guards the picker list against the locale folders on disk, in both directions.

// 1. src/engine/types.ts — the union the whole engine is typed against
export type SupportedLanguage = "en" | "vi" | "ja" | "es" | "ko" | "zh" | "pt-BR" | "id" | "fr";

// 2. src/i18n/index.ts — every language picker shows `nativeName (id)`.
//    `flag` is no longer displayed, but the registration test requires it.
export const SUPPORTED_LANGUAGES = [
  // …
  { id: "fr", label: "French", flag: "🇫🇷", nativeName: "Français" },
] as const satisfies readonly {
  id: SupportedLanguage;
  label: string;
  flag: string;
  nativeName: string;
}[];

// 3. src/store/settings-heal.ts — detectBrowserLanguage's own copy of the list.
//    Bare codes go in `supported`, region-qualified ones (like "pt-BR") in `REGIONAL`.
//    Miss this and the language works, but is never auto-selected for a
//    first-time visitor whose browser is set to it.
const supported: SupportedLanguage[] = ["en", "vi", "ja", "es", "ko", "zh", "id", "fr"];

// 4. src/engine/tag-generator.ts — CORE_TAGS_BY_LANG + MULTILINGUAL_TAGS (Step 6)
// 5. src/engine/channel-phrase.ts — DROP + FALLBACK (Step 5)

The satisfies clause makes an id that isn't in the union a compile error. Items 4 and 5 are Record<SupportedLanguage, …>, so TypeScript catches those too once the union has the new code.

Two more places, outside src/:

  • worker/gate-i18n.ts — the Turnstile gate page, the first screen every web visitor sees, has its own copy of the languages: add the code to GateLang, its strings to GATE_STRINGS, and its Accept-Language prefix to PREFIX_TO_LANG. GateLang is not tied to SupportedLanguage, so a miss is silent — those visitors get the gate page in English. Update tests/worker/gate-i18n.test.ts too; it pins the list of gate languages.
  • DISCLAIMER.md (and docs/i18n/vi/DISCLAIMER.md) — add the locale to the translation-quality table.

Optional: if the new locale is human-reviewed, add it to TRANSLATION_TRUSTED in src/engine/description-builder.ts so it doesn't get the AI-translation note, and update description.translationQuality.intro (which names the reviewed languages) in every locale.

npm run generate:locale prints a shorter checklist on success; the list above is the complete one.

No import or resources edits needed (v0.26+): locales are lazy-loaded through a dynamic import("./locales/<code>/<ns>.json"), so Vite picks the new files up automatically as async chunks — the file names must stay exactly ui.json and templates.json. Only English is eagerly bundled (it's the fallbackLng and the engine's bilingual tEn source); don't add static imports for other languages, that would drag them back into the main chunk.

Step 5: Channel-phrase patterns

Without a channel name, sentences such as "…of Hades on {{channelName}}." must not end in "on ." (fixed in v1.0.0). The engine renders {{channelName}} as a placeholder, then removes the words that go with it, per language:

// src/engine/channel-phrase.ts
const DROP: Record<SupportedLanguage, readonly RegExp[]> = {
  // …
  "pt-BR": [new RegExp(`\\s+no ${S}`, "g")], // "…de Hades no {{channelName}}." → "…de Hades."
};

/** For a sentence shape none of the patterns covers: a neutral stand-in. */
const FALLBACK: Record<SupportedLanguage, string> = {
  // …
  "pt-BR": "este canal",
};

Write the patterns for the phrases your templates.json actually uses. Then add the code to LANGS in tests/engine/channel-phrase.test.ts: it renders every template that names the channel with an empty channel and fails on any leftover.

Step 6: Tag pools

// src/engine/tag-generator.ts
export const CORE_TAGS_BY_LANG: Record<SupportedLanguage, (gameName: string) => string[]> = {
  // …
  "pt-BR": (g) => [
    `${g} gameplay`,
    `${g} sem comentários`,
    "gameplay sem comentários",
    `${g} detonado`,
    `${g} jogo completo`,
    `${g} gameplay sem comentarios`,
  ],
};

export const MULTILINGUAL_TAGS: Record<SupportedLanguage, (gameName: string) => string[]> = {
  // …
  "pt-BR": (g) => [`${g} português`, `${g} em português`, "gameplay em português"],
};

Core tags come right after the game name in the tag list; multilingual tags are added when Settings › Include Multilingual Tags is on, for the output language only. Tags longer than 30 characters are dropped, and the registration test checks that each language's core tags use the game name.

Step 7: Check the font

The bundled Inter font covers Latin (including Vietnamese), Cyrillic and Greek. Other scripts use the system fonts in --font-sans-stack (src/styles/globals.css), which already lists Noto Sans JP / KR / SC for CJK — add a fallback there if the new language uses another script.

Step 8: Validate

npm run validate:locales
# Checks all locale files have the same keys as _schema.json
# Reports missing/extra keys per language

Step 9: Test

npm run test:run -- tests/i18n tests/engine/channel-phrase.test.ts tests/engine/tag-generator.test.ts tests/worker/gate-i18n.test.ts
# Then the whole suite and the type check
npm run test:run
npm run typecheck && npm run typecheck:all

Locale Validation Script

The scripts/validate-locales.ts script checks every locale folder against _schema.json. At v1.3.0 (1,264 UI + 584 template keys per locale):

✓ en/ui.json — 1264/1264 keys
✓ en/templates.json — 584/584 keys
✓ es/ui.json — 1264/1264 keys
✓ es/templates.json — 584/584 keys
…
✓ zh/templates.json — 584/584 keys

All locale files are complete!

A gap fails the run and names the keys:

✗ fr/ui.json — 1245/1247 keys
  Missing: editor.quick.nextPart, editor.quick.newVideo

Template Interpolation

Templates use {{variable}} syntax (i18next default):

"intro": "This video features the full gameplay of {{gameName}} on {{channelName}}."

The engine gets a t fixed to the output language and passes the variables:

// src/hooks/use-generated-output.ts
const t = i18n.getFixedT(input.language, "templates");

// src/engine/description-builder.ts
const intro = t(`description.intro.${input.videoType}`, {
  gameName,
  channelName: channelOrSlot(input.channelName), // a placeholder when there is no channel
  partNumber: input.partNumber ?? "",
  // …
});
sections.push(withoutEmptyChannel(intro, input.language));

RTL Language Support (Arabic)

Not supported yet. Arabic (ar) would need dir="rtl" on <html> — set next to lang, which src/main.tsx updates on every languageChanged — and a right-to-left pass over the layout.

Contributing Translations

Community members can contribute translations by:

  1. Fork the repository
  2. Run npm run generate:locale -- --lang {code} (or copy src/i18n/locales/en/ to src/i18n/locales/{code}/)
  3. Translate all strings in both files
  4. Register the language (Step 4 above)
  5. Run npm run validate:locales and the tests in Step 9
  6. Submit a PR with the new locale files

Native-speaker corrections to the AI-translated locales are the most welcome contribution of all. src/i18n/locales/<code>/*.json can be edited straight from GitHub's web UI; see CONTRIBUTING.md.