Files
youtube-generator/docs/I18N.md
T
poli0981andClaude Opus 4.6 a763f7c78a feat: Phase 1 MVP scaffold — core engine, i18n, UI, CI/CD
Complete Phase 1 implementation of YTDescGen:
- Project setup: Vite 5 + React 18 + TypeScript strict + Tailwind CSS dark theme
- Config layer: 7 video types, 10 genres, 7 platforms, rig/social fields
- i18n: EN/VI/JA with separate UI and template namespaces + validation script
- Core engine: title-builder, description-builder, tag-generator (pure TS, zero React)
- 42 unit tests covering all engine functions
- Zustand stores: editor + settings with localStorage persistence
- UI: 6 primitives, 11 editor components, 4 output components, 3 layout components
- Pages: Editor (form + quick preview) and Output (title/desc/tags + copy)
- CI/CD: GitHub Actions for lint/typecheck/test/build + GitHub Pages deploy

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 21:46:59 +07:00

9.4 KiB

Internationalization Guide (i18n)

YTDescGen — Adding & Managing Languages


Overview

YTDescGen has two independent language contexts:

  1. UI Language — The app interface (buttons, labels, tooltips). Controlled by SettingsStore.defaultLanguage. Affects how the app looks.
  2. Output Language — The generated title/description/tags. Controlled by EditorStore.language. Affects what the app produces.

These are independent: a Vietnamese user can browse the app in Vietnamese (UI) while generating descriptions in Japanese (output).

File Structure

src/i18n/
├── index.ts                # i18next initialization + language registration
├── locales/
│   ├── _schema.json        # JSON Schema defining all required keys
│   ├── en/
│   │   ├── ui.json          # UI strings (buttons, labels, errors, tooltips)
│   │   └── templates.json   # Generated content (title, description patterns)
│   ├── vi/
│   │   ├── ui.json
│   │   └── templates.json
│   ├── ja/
│   │   ├── ui.json
│   │   └── templates.json
│   └── es/                  # Example: adding Spanish
│       ├── ui.json
│       └── templates.json

Adding a New Language — Checklist

Step 1: Create locale files

# Generate empty locale from schema
npm run generate:locale -- --lang es

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

Or copy from English and translate:

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

Step 2: Translate ui.json

// src/i18n/locales/es/ui.json
{
  "app": {
    "title": "Generador de Descripción YT",
    "subtitle": "Motor de plantillas Gameplay No Commentary"
  },
  "tabs": {
    "editor": "✏️ Editor",
    "output": "📄 Resultado",
    "profiles": "💾 Perfiles",
    "history": "📜 Historial",
    "settings": "⚙️ Ajustes",
    "batch": "📦 Lote"
  },
  "editor": {
    "videoType": "Tipo de Video",
    "language": "Idioma",
    "genre": "Género del Juego",
    "gameName": "Nombre del Juego",
    "channelName": "Nombre del Canal",
    "platform": "Plataforma",
    "resolution": "Resolución",
    "fps": "FPS",
    "graphics": "Gráficos",
    "timestamps": "Marcas de Tiempo",
    "storeLinks": "Enlaces de Tienda",
    "rig": "Mi PC",
    "social": "Redes Sociales y Donaciones",
    "warnings": "Advertencias",
    "spoilerWarning": "Advertencia de Spoiler",
    "matureWarning": "Contenido para Adultos (18+)",
    "playlistLink": "Enlace de Lista de Reproducción",
    "contactEmail": "Correo de Contacto"
  },
  "output": {
    "title": "📌 Título",
    "description": "📝 Descripción",
    "tags": "🏷 Etiquetas",
    "copyTitle": "Copiar Título",
    "copyDescription": "Copiar Descripción",
    "copyTags": "Copiar Etiquetas",
    "copyAll": "📋 Copiar Todo",
    "copied": "✓ ¡Copiado!",
    "charCount": "{{count}}/{{limit}}"
  },
  "profiles": {
    "saveProfile": "Guardar Perfil",
    "loadProfile": "Cargar",
    "deleteProfile": "Eliminar",
    "profileName": "Nombre del Perfil",
    "noProfiles": "No hay perfiles guardados.",
    "gamePresets": "Preajustes de Juegos"
  },
  "common": {
    "save": "Guardar",
    "cancel": "Cancelar",
    "delete": "Eliminar",
    "confirm": "Confirmar",
    "export": "Exportar",
    "import": "Importar",
    "reset": "Restablecer",
    "search": "Buscar"
  },
  "videoTypes": {
    "full": "Gameplay Completo",
    "part": "Gameplay Parte",
    "boss": "Pelea de Jefe",
    "boss_nohit": "Jefe Sin Golpes",
    "ending": "Final / Todos los Finales",
    "speedrun": "Speedrun",
    "100percent": "100% Completado",
    "dlc": "Contenido DLC",
    "newgame_plus": "New Game+",
    "challenge": "Desafío",
    "side_quest": "Misiones Secundarias",
    "secret": "Secretos / Ocultos",
    "comparison": "Comparación de Gráficos",
    "guide": "Guía Silenciosa"
  }
}

Step 3: Translate templates.json

// src/i18n/locales/es/templates.json
{
  "title": {
    "separator": " — ",
    "suffix": "Gameplay No Commentary",
    "videoType": {
      "full": "",
      "part": "Parte {{partNumber}}",
      "boss": "{{bossName}} Pelea de Jefe",
      "boss_nohit": "{{bossName}} Jefe Sin Golpes",
      "ending": "Final",
      "speedrun": "Speedrun",
      "100percent": "100%",
      "dlc": "{{dlcName}} DLC",
      "newgame_plus": "New Game+",
      "challenge": "Desafío {{challengeName}}",
      "side_quest": "Misiones Secundarias",
      "secret": "Secretos",
      "comparison": "Comparación",
      "guide": "Guía"
    }
  },
  "description": {
    "intro": {
      "full": "Este video presenta el gameplay completo de {{gameName}} en {{channelName}}.",
      "part": "Este video presenta la Parte {{partNumber}} de {{gameName}} en {{channelName}}.",
      "boss": "Este video presenta la pelea de jefe {{bossName}} de {{gameName}} en {{channelName}}.",
      "boss_nohit": "Este video presenta la pelea de jefe {{bossName}} (sin golpes) de {{gameName}} en {{channelName}}.",
      "ending": "Este video presenta el final de {{gameName}} en {{channelName}}.",
      "speedrun": "Este video presenta un speedrun de {{gameName}} en {{channelName}}.",
      "100percent": "Este video presenta el 100% completado de {{gameName}} en {{channelName}}.",
      "dlc": "Este video presenta el DLC {{dlcName}} de {{gameName}} en {{channelName}}.",
      "newgame_plus": "Este video presenta el New Game+ de {{gameName}} en {{channelName}}.",
      "challenge": "Este video presenta el desafío {{challengeName}} de {{gameName}} en {{channelName}}.",
      "side_quest": "Este video presenta las misiones secundarias de {{gameName}} en {{channelName}}.",
      "secret": "Este video presenta los secretos y contenido oculto de {{gameName}} en {{channelName}}.",
      "comparison": "Este video compara los gráficos de {{gameName}} en {{channelName}}.",
      "guide": "Este video es una guía silenciosa de {{gameName}} en {{channelName}}."
    },
    "noCommentaryLine": "Sin comentarios — gameplay puro para tu disfrute.",
    "sections": {
      "timestamps": "⏱ MARCAS DE TIEMPO",
      "storeLinks": "🎮 OBTENER EL JUEGO",
      "videoSettings": "🖥 AJUSTES DE VIDEO: {{settings}}",
      "rig": "💻 MI PC",
      "spoilerWarning": "⚠️ ADVERTENCIA DE SPOILER: Este video contiene spoilers. ¡Míralo bajo tu propio riesgo!",
      "matureWarning": "🔞 CONTENIDO PARA ADULTOS (18+): Contiene violencia / lenguaje fuerte / contenido gráfico.",
      "playlist": "▶️ Ver la serie completa: {{link}}",
      "contact": "📧 Consultas comerciales: {{email}}",
      "cta": "👍 Me gusta | 🔔 Suscríbete | ↗️ Comparte"
    }
  },
  "tags": {
    "multilingual": [
      "{{gameName}} sin comentarios",
      "{{gameName}} gameplay completo",
      "juego de acción sin comentarios"
    ]
  }
}

Step 4: Register the language

// src/i18n/index.ts — add to SUPPORTED_LANGUAGES
export const SUPPORTED_LANGUAGES = [
  { id: "en", label: "English", flag: "🇬🇧", nativeName: "English" },
  { id: "vi", label: "Vietnamese", flag: "🇻🇳", nativeName: "Tiếng Việt" },
  { id: "ja", label: "Japanese", flag: "🇯🇵", nativeName: "日本語" },
  { id: "es", label: "Spanish", flag: "🇪🇸", nativeName: "Español" },  // ← Add here
] as const;

// Add resource import
import esUI from "./locales/es/ui.json";
import esTemplates from "./locales/es/templates.json";

// Add to i18next resources
resources: {
  // ...existing
  es: { ui: esUI, templates: esTemplates },
}

Step 5: Add multilingual tag pool

// src/engine/tag-generator.ts — add to MULTILINGUAL_TAG_POOLS
multilingual_es: (gameName: string) => [
  `${gameName} sin comentarios`,
  `${gameName} gameplay completo`,
  `juego sin comentarios`,
],

Step 6: Validate

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

Step 7: Test

npm run test -- --grep "i18n"
# Runs i18n-related tests including new language

Locale Validation Script

The scripts/validate-locales.ts script ensures all locale files are complete:

✓ en/ui.json — 47/47 keys
✓ en/templates.json — 32/32 keys
✓ vi/ui.json — 47/47 keys
✓ vi/templates.json — 32/32 keys
✓ ja/ui.json — 47/47 keys
✓ ja/templates.json — 32/32 keys
✗ es/ui.json — 45/47 keys (missing: editor.dlcName, editor.challengeName)
✓ es/templates.json — 32/32 keys

Template Interpolation

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

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

Engine passes variables:

t("templates:description.intro.full", {
  gameName: state.gameName,
  channelName: state.channelName,
});

RTL Language Support (Arabic)

For Arabic (ar), add RTL handling:

// src/i18n/index.ts
export const RTL_LANGUAGES = ["ar"] as const;

// src/App.tsx — set dir attribute
const isRTL = RTL_LANGUAGES.includes(currentLanguage);
<div dir={isRTL ? "rtl" : "ltr"}>

Contributing Translations

Community members can contribute translations by:

  1. Fork the repository
  2. Copy src/i18n/locales/en/ to src/i18n/locales/{code}/
  3. Translate all strings
  4. Run npm run validate:locales to check completeness
  5. Submit a PR with the new locale files