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>
9.4 KiB
9.4 KiB
Internationalization Guide (i18n)
YTDescGen — Adding & Managing Languages
Overview
YTDescGen has two independent language contexts:
- UI Language — The app interface (buttons, labels, tooltips). Controlled by
SettingsStore.defaultLanguage. Affects how the app looks. - 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:
- Fork the repository
- Copy
src/i18n/locales/en/tosrc/i18n/locales/{code}/ - Translate all strings
- Run
npm run validate:localesto check completeness - Submit a PR with the new locale files