Files
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

408 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](../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:
```json
{
"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](./ROADMAP.md).
### Step 1: Create locale files
```bash
# 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:
```bash
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):
```json
{
"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`:
```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.
```typescript
// 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:
```typescript
// 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
```typescript
// 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
```bash
npm run validate:locales
# Checks all locale files have the same keys as _schema.json
# Reports missing/extra keys per language
```
### Step 9: Test
```bash
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):
```json
"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:
```typescript
// 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](../CONTRIBUTING.md).