Shiip-of-Hakinian-Espanol/instrucciones_traducción.txt

================================================================================
GUÍA PARA AGREGAR NUEVAS TRADUCCIONES AL ESPAÑOL.JSON
================================================================================

Este archivo explica cómo encontrar nuevos textos hardcodeados en el código
y agregarlos al archivo de traducción Espanol.json.

================================================================================
PASO 1: IDENTIFICAR TEXTOS HARDCODEADOS EN EL CÓDIGO
================================================================================

Los textos que aparecen en el menú están en archivos .cpp dentro de:
  soh/soh/SohGui/

Los archivos principales son:
  - SohMenuSettings.cpp   (Configuración del menú)
  - SohMenuEnhancements.cpp (Mejoras del juego)
  - SohMenuRandomizer.cpp  (Randomizer)
  - SohMenuNetwork.cpp     (Red)
  - SohMenuDevTools.cpp    (Herramientas de desarrollo)
  - Menu.cpp               (Sistema de menús)

Para buscar textos hardcodeados, usa estos patrones:

  1. Buscar en AddWidget (texto visible en el menú):
     grep -n 'AddWidget.*"' soh/soh/SohGui/*.cpp

  2. Buscar en AddSidebarEntry (entradas de barra lateral):
     grep -n 'AddSidebarEntry' soh/soh/SohGui/*.cpp

  3. Buscar en AddMenuEntry (títulos de menú):
     grep -n 'AddMenuEntry' soh/soh/SohGui/*.cpp


================================================================================
PASO 2: IDENTIFICAR EL TEXTO EXACTO A TRADUCIR
================================================================================

Ejemplo de búsqueda:

  $ grep -n 'AddWidget' soh/soh/SohGui/SohMenuSettings.cpp | head -20

Resultado:
  163:     AddWidget(path, "Menu Settings", WIDGET_SEPARATOR_TEXT);
  164:     AddWidget(path, "Menu Theme", WIDGET_CVAR_COMBOBOX)
  172:     AddWidget(path, "Menu Controller Navigation", WIDGET_CVAR_CHECKBOX)
  179:     AddWidget(path, "Allow background inputs", WIDGET_CVAR_CHECKBOX)

El texto a traducir es lo que aparece entre comillas después de la coma:
  - "Menu Settings"      -> traducir como "Menu Settings"
  - "Menu Theme"         -> traducir como "Menu Theme"
  - "Allow background inputs" -> traducir como "Allow background inputs"


================================================================================
PASO 3: VERIFICAR SI YA EXISTE LA TRADUCCIÓN
================================================================================

Antes de agregar una traducción, verifica si ya existe:

  $ grep -i '"texto_a_buscar"' lenguajes/Espanol.json

O busca en el archivo directamente:
  $ grep '"Menu Settings"' lenguajes/Espanol.json


================================================================================
PASO 4: AGREGAR LA TRADUCCIÓN AL JSON
================================================================================

El archivo JSON tiene esta estructura:

  {
    "language": "Español",
    "strings": {
      "TEXTO_EN_INGLÉS": "TEXTO_EN_ESPAÑOL",
      ...
    }
  }

Ejemplo 1 - Agregar una traducción simple:

  Buscas en el código:
    AddWidget(path, "Allow background inputs", WIDGET_CVAR_CHECKBOX)

  Agregas al JSON:
    "Allow background inputs": "Permitir entradas en segundo plano",

Ejemplo 2 - Agregar una traducción con variable (%d):

  Buscas en el código:
    AddWidget(path, "Master Volume: %d %%", WIDGET_CVAR_SLIDER_INT)

  Agregas al JSON (mantén el formato %d):
    "Master Volume: %d %%": "Volumen Principal: %d %%",

Ejemplo 3 - Agregar texto de barra lateral:

  Buscas en el código:
    AddSidebarEntry("Settings", "Audio", 3);

  Agregas al JSON:
    "Audio": "Audio",

Ejemplo 4 - Agregar texto de menú principal:

  Buscas en el código:
    AddMenuEntry("Enhancements", CVAR_SETTING("Menu.EnhancementsSidebarSection"));

  Agregas al JSON:
    "Enhancements": "Mejoras",


================================================================================
PASO 5: ORDENAR LAS ENTRADAS EN EL JSON (OPCIONAL)
================================================================================

Para mantener el JSON organizado, puedes ordenar las entradas alfabéticamente
o por categoría. Las categorías principales son:

  - Configuración del menú: Menu Settings, Boot, Languages, etc.
  - Graphics: Resolution, Aspect Ratio, etc.
  - Audio: Volumes, API, etc.
  - Enhancements: Saving, Cutscenes, Items, etc.
  - Randomizer: Seed, Settings, Trackers, etc.
  - Network: Sail, Crowd Control, etc.
  - DevTools: Debug, Stats, Editors, etc.


================================================================================
PASO 6: PROBAR LAS TRADUCCIONES
================================================================================

1. Compila el proyecto:
   cmake --build build-cmake -j$(nproc)

2. Copia la carpeta de idiomas al ejecutable:
   cp -r lenguajes build-cmake/soh/

3. Ejecuta el juego y verifica que las traducciones aparezcan.

4. Si algo no funciona, revisa:
   - Que el JSON sea válido (sin comas extras o faltantes)
   - Que el texto en el código coincida exactamente con la clave en el JSON
   - Que no haya caracteres especiales mal escapados


================================================================================
EJEMPLO COMPLETO: AGREGAR "Autosave"
================================================================================

1. Buscas en el código:
   $ grep -n 'Autosave' soh/soh/SohGui/SohMenuEnhancements.cpp

   Resultado:
   148:     AddWidget(path, "Autosave", WIDGET_CVAR_CHECKBOX)

2. Verificas si ya existe:
   $ grep '"Autosave"' lenguajes/Espanol.json

   Resultado: No existe

3. Agregas al JSON (busca un lugar lógico, cerca de "Saving"):
   Buscas en el JSON:
     "Saving": "Guardado",

   Agregas después:
     "Autosave": "Guardado Automático",

4. Quedaría así en el JSON:
     "Saving": "Guardado",
     "Autosave": "Guardado Automático",


================================================================================
REGLAS IMPORTANTES
================================================================================

1. Mantén las claves en INGLÉS (el texto original del código)
2. Los valores deben ser la traducción al ESPAÑOL
3. Usa comas correctamente (todas las claves excepto la última deben tener coma)
4. No uses caracteres especiales que requieran escape en JSON (\" debe ser \")
5. Mantén el formato de printf si existe (%d, %s, %.2f, etc.)
6. Las claves con ## son para botones con el mismo nombre (ej: "All##Skips")


================================================================================
LISTA DE ARCHIVOS CLAVE DEL SISTEMA DE TRADUCCIÓN
================================================================================

  - soh/soh/SohGui/LanguageManager.h    -> Header del manager de idiomas
  - soh/soh/SohGui/LanguageManager.cpp  -> Implementación
  - lenguajes/Espanol.json              -> Archivo de traducciones
  - soh/soh/SohGui/SohMenuSettings.cpp  -> Selector de idioma
  - soh/soh/SohGui/SohMenu.cpp          -> Aplicación de traducciones


================================================================================
COMANDOS ÚTILES
================================================================================

# Buscar todos los AddWidget con texto:
grep -n 'AddWidget.*WIDGET' soh/soh/SohGui/*.cpp | head -50

# Buscar textos específicos:
grep -i "texto_a_buscar" soh/soh/SohGui/*.cpp

# Contar líneas del JSON:
wc -l lenguajes/Espanol.json

# Validar JSON (requiere python):
python3 -m json.tool lenguajes/Espanol.json > /dev/null && echo "JSON válido"


================================================================================
FIN DEL DOCUMENTO
================================================================================