 Instrucciones para añadir traducciones a Ship of Harkinian

  Este documento te guía sobre cómo añadir nuevas traducciones para los menús y la interfaz de usuario del proyecto Ship of Harkinian.

  ---

  1. Cómo funciona el sistema de localización:

  El sistema utiliza un sistema basado en claves y archivos JSON para gestionar los textos traducibles.

   * Código C++: Utiliza la macro LUS_LOC("CLAVE_UNICA") para marcar los textos que deben ser traducidos.
   * Archivos JSON (languages/es_ES.json y languages/en_US.json): Actúan como diccionarios. Mapean cada CLAVE_UNICA a su correspondiente texto traducido. El sistema
     carga el archivo JSON según el idioma seleccionado.

  ---

  2. Pasos para añadir una nueva traducción:

  Sigue estos pasos para traducir un nuevo texto que encuentres en el código:

  Paso 1: Identificar el texto en inglés en el código C++

   * Busca cadenas de texto literales (entre comillas " como "Debug Mode", "Sets the opacity...") en los archivos .cpp del proyecto.
   * Los lugares más comunes para encontrar estos textos son:
       * Llamadas a funciones de ImGui: ImGui::Text("..."), ImGui::Button("...").
       * Opciones de widgets de UIWidgets: Tooltip("..."), Label("...").
       * Textos en separadores: ImGui::SeparatorText("...").
   * Ejemplo: Si encuentras ImGui::Text("Game Over"); o .Options(CheckboxOptions().Tooltip("Makes the cursor always visible."));.

  Paso 2: Crear una clave única y descriptiva

   * Inventa un nombre para tu clave. Debe ser único y fácil de reconocer.
   * Se recomienda usar mayúsculas y guiones bajos (_) para separar palabras.
   * Utiliza prefijos para indicar la sección o tipo de texto:
       * MENU_ para títulos de menús principales (ej: MENU_SETTINGS).
       * SIDEBAR_ para entradas de barras laterales (ej: SIDEBAR_GRAPHICS).
       * WIDGET_ para etiquetas de opciones de widgets (ej: WIDGET_AUTOSAVE).
       * TOOLTIP_ para textos de ayuda emergentes (ej: TOOLTIP_MENU_LANGUAGE).
       * OPTION_ para valores específicos de opciones (ej: OPTION_GAMEPLAY_MOON_JUMP).
   * Ejemplos de Claves:
       * WIDGET_DEBUG_MODE
       * TOOLTIP_GRAPHICS_VSYNC
       * OPTION_GAMEPLAY_MOON_JUMP

  Paso 3: Actualizar los archivos JSON

   * Abre los archivos languages/en_US.json y languages/es_ES.json.
   * Añade la clave que creaste y su correspondiente texto.

      Ejemplo para la clave WIDGET_DEBUG_MODE:

       * En languages/en_US.json:
   1         "WIDGET_DEBUG_MODE": "Debug Mode"
       * En languages/es_ES.json:

   1         "WIDGET_DEBUG_MODE": "Modo Depuración"

      Ejemplo para un tooltip de Vsync:

       * En languages/en_US.json:

   1         "TOOLTIP_GRAPHICS_VSYNC": "Enables Vsync to limit framerate to display refresh rate."
       * En languages/es_ES.json:

   1         "TOOLTIP_GRAPHICS_VSYNC": "Activa Vsync para limitar los FPS a la tasa de refresco de tu pantalla."

  Paso 4: Modificar el código C++ (Solo si es necesario)

   * Para textos literales directamente en ImGui/UIWidgets: Si encuentras una línea como ImGui::Text("Game Over"); o UIWidgets::Button("Ok", ...) que no usa widget.name
     u otra variable, reemplaza la cadena literal por LUS_LOC("TU_CLAVE_UNICA").c_str().
       * Ejemplo (Texto simple):
           * Antes: ImGui::Text("Game Over");
           * Después: ImGui::Text(LUS_LOC("GAME_OVER_TEXT").c_str());
       * Ejemplo (Tooltip):
           * Antes: .Options(FloatSliderOptions().Tooltip("Sets the opacity of the background of the port menu."))
           * Después: .Options(FloatSliderOptions().Tooltip(LUS_LOC("TOOLTIP_MENU_BACKGROUND_OPACITY")))

   * Para nombres de widgets (checkboxes, sliders, etc.):
       * IMPORTANTE: Como hemos visto, traducir directamente los nombres de los widgets (widget.name) de forma automática puede causar errores de compilación. Por ahora,
         es más seguro dejar estos nombres en inglés en el código C++ (widget.name.c_str()).
       * Si en el futuro el sistema de UIWidgets se actualiza para manejar la localización de estos nombres de forma más robusta, podrás aplicar LUS_LOC() a widget.name
         en esos casos.

  Paso 5: Compilar (Solo si modificaste código C++)

   * Si realizaste cambios en archivos .cpp o .h, necesitarás recompilar el proyecto:
   1     cmake --build build-cmake -j$(nproc)
   * Si solo modificaste los archivos .json, no necesitas recompilar. Los cambios de idioma se aplicarán al reiniciar el juego.

  ---

  Recomendación:
  Empieza buscando textos simples que se muestren directamente al usuario (como ImGui::Text o los tooltips). Son los más fáciles de localizar. Cuando encuentres un
  texto, crea su clave, añádelo a los JSON y luego modifica la línea de código para usar LUS_LOC("TU_CLAVE").c_str().


  --- INICIO DEL CONTENIDO ---
  Instrucciones para añadir traducciones a Ship of Harkinian

  Este documento te guía sobre cómo añadir nuevas traducciones para los menús y la interfaz de usuario del proyecto Ship of Harkinian.

  2. Cómo funciona el sistema de localización:

  El sistema utiliza un sistema basado en claves y archivos JSON para gestionar los textos traducibles.

   * Código C++: Utiliza la macro LUS_LOC("CLAVE_UNICA") para marcar los textos que deben ser traducidos.
   * Archivos JSON (languages/es_ES.json y languages/en_US.json): Actúan como diccionarios. Mapean cada CLAVE_UNICA a su correspondiente texto traducido. El sistema
     carga el archivo JSON según el idioma seleccionado.

  3. Pasos para añadir una nueva traducción:

  Sigue estos pasos para traducir un nuevo texto que encuentres en el código:

  Paso 1: Identificar el texto en inglés en el código C++

   * Busca cadenas de texto literales (entre comillas " como "Debug Mode", "Sets the opacity...") en los archivos .cpp del proyecto. Los lugares más comunes son:
       * Llamadas a funciones de ImGui: ImGui::Text("..."), ImGui::Button("...").
       * Opciones de widgets de UIWidgets: Tooltip("..."), Label("...").
       * Textos en separadores: ImGui::SeparatorText("...").
   * Ejemplo: Si encuentras ImGui::Text("Game Over"); o .Options(CheckboxOptions().Tooltip("Makes the cursor always visible."));.

  Paso 2: Crear una clave única y descriptiva

   * Inventa un nombre para tu clave. Debe ser único y fácil de reconocer.
   * Se recomienda usar mayúsculas y guiones bajos (_) para separar palabras.
   * Utiliza prefijos para indicar la sección o tipo de texto:
       * MENU_ para títulos de menús principales (ej: MENU_SETTINGS).
       * SIDEBAR_ para entradas de barras laterales (ej: SIDEBAR_GRAPHICS).
       * WIDGET_ para etiquetas de opciones de widgets (ej: WIDGET_AUTOSAVE).
       * TOOLTIP_ para textos de ayuda emergentes (ej: TOOLTIP_MENU_LANGUAGE).
       * OPTION_ para valores específicos de opciones (ej: OPTION_GAMEPLAY_MOON_JUMP).
   * Ejemplos de Claves:
       * WIDGET_DEBUG_MODE
       * TOOLTIP_GRAPHICS_VSYNC
       * OPTION_GAMEPLAY_MOON_JUMP

  Paso 3: Actualizar los archivos JSON

   * Abre los archivos languages/en_US.json y languages/es_ES.json.
   * Añade la clave que creaste y su correspondiente texto.

      Ejemplo para la clave WIDGET_DEBUG_MODE:

       * En languages/en_US.json:
   1         "WIDGET_DEBUG_MODE": "Debug Mode"
       * En languages/es_ES.json:

   1         "WIDGET_DEBUG_MODE": "Modo Depuración"

      Ejemplo para un tooltip de Vsync:

       * En languages/en_US.json:

   1         "TOOLTIP_GRAPHICS_VSYNC": "Enables Vsync to limit framerate to display refresh rate."
       * En languages/es_ES.json:
   1         "TOOLTIP_GRAPHICS_VSYNC": "Activa Vsync para limitar los FPS a la tasa de refresco de tu pantalla."

  Paso 4: Modificar el código C++ (Solo si es necesario)

   * Para textos literales directamente en ImGui/UIWidgets: Si encuentras una línea como ImGui::Text("Game Over"); o UIWidgets::Button("Ok", ...) que no usa widget.name
     u otra variable, reemplaza la cadena literal por LUS_LOC("TU_CLAVE_UNICA").c_str().
       * Ejemplo (Texto simple):
           * Antes: ImGui::Text("Game Over");
           * Después: ImGui::Text(LUS_LOC("GAME_OVER_TEXT").c_str());
       * Ejemplo (Tooltip):
           * Antes: .Options(FloatSliderOptions().Tooltip("Sets the opacity of the background of the port menu."))
           * Después: .Options(FloatSliderOptions().Tooltip(LUS_LOC("TOOLTIP_MENU_BACKGROUND_OPACITY")))

   * Para nombres de widgets (checkboxes, sliders, etc.):
       * IMPORTANTE: Como hemos visto, traducir directamente los nombres de los widgets (widget.name) de forma automática puede causar errores de compilación. Por ahora,
         es más seguro dejar estos nombres en inglés en el código C++ (widget.name.c_str()). Si necesitas traducir una etiqueta de widget visible, deberás identificar
         cómo se pasa ese texto a la función de ImGui/UIWidgets y aplicarle LUS_LOC() de forma segura, similar a los ejemplos de ImGui::Text o Tooltip.

  Paso 5: Compilar (Solo si modificaste código C++)

   * Si realizaste cambios en archivos .cpp o .h, necesitarás recompilar el proyecto:
   1     cmake --build build-cmake -j$(nproc)
   * Si solo modificaste los archivos .json, no necesitas recompilar. Los cambios de idioma se aplicarán al reiniciar el juego.

