Configuración

Descripción general

El archivo gt.config.json se utiliza para configurar los ajustes de GT de tu proyecto. Debe colocarse en la raíz de tu proyecto.

El asistente de configuración de CLI npx gtx-cli init creará un archivo gt.config.json para ti en tu proyecto.

Configuración

El archivo gt.config.json acepta las siguientes propiedades, pero no se limita a ellas:

• defaultLocale: El idioma predeterminado para tu proyecto. Este es el idioma en el que está escrito tu contenido fuente. También es el idioma de respaldo para tu proyecto (si usas gt-next o gt-react).

• locales: Un array de idiomas para tu proyecto. Estos son los idiomas a los que quieres traducir tu proyecto. Consulta los idiomas soportados para más información. Si estás usando gt-next o gt-react, estos también son los idiomas que tu aplicación soporta.

• files: Este es un objeto que contiene información sobre el contenido que quieres traducir.

• stageTranslations: Una bandera booleana opcional que indica si tu proyecto está configurado para usar revisión humana.

• src: Un array opcional de patrones glob de archivos para tus archivos fuente. Por defecto, se establece en:

[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]

• dictionary: Una cadena opcional que especifica la ruta relativa al archivo de diccionario.

{
  "$schema": "https://assets.gtx.dev/config-schema.json",
}

Aquí tienes un esqueleto del archivo gt.config.json:

{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "..."
    },
    "json": {
      "include": [...]
    },
    "mdx": {
      "include": [...]
    },
    "md": {
      "include": [...]
    }
  },
  "src": [
    "src/**/*.{ts,tsx}",
  ],
  "dictionary": "./dictionary.json"
}

files

Tipos de Archivo Soportados

files debe contener una clave para cada tipo de archivo que desees traducir. Puedes configurar tu proyecto para mezclar y combinar diferentes tipos de archivos, y hacer que todos sean traducidos. Actualmente soportamos los siguientes tipos de archivo:

• gt: Archivos de General Translation.
• json: Archivos JSON.
• yaml: Archivos YAML.
• mdx: Archivos de componente Markdown (MDX).
• md: Archivos Markdown (MD).
• js: Archivos JavaScript.
• ts: Archivos TypeScript.

Cada tipo de archivo debe corresponder a un objeto que contenga una o más de las siguientes claves:

• include
• exclude
• transform
• output

include

Si se usa, el valor de la clave include debe ser un array de patrones glob que coincidan con los archivos que deseas traducir.

Debes usar el marcador de posición [locale] en tus patrones glob para asegurar que los archivos fuente se encuentren correctamente, y los archivos traducidos se guarden en la ubicación correcta. La herramienta CLI reemplazará el marcador de posición [locale] con el valor de defaultLocale al buscar archivos traducibles.

La herramienta CLI guardará los archivos traducidos en la ruta correspondiente, con el marcador de posición [locale] reemplazado por el código de idioma de destino.

{
  "include": ["docs/[locale]/**/*.json"]
}

exclude

Si se usa, el valor de la clave exclude debe ser un array de patrones glob que coincidan con los archivos que deseas excluir de la traducción.

El patrón es el mismo que el patrón include, con la excepción de que el marcador de posición [locale] es opcional. Si se proporciona, será reemplazado con el valor de defaultLocale.

{
  "exclude": ["docs/[locale]/exclude/**/*.json"]
}

Si deseas excluir archivos de la traducción para todos los idiomas, puedes usar el marcador de posición [locales] en lugar de [locale].

{
  "exclude": ["docs/[locales]/exclude/**/*.json"]
}

transform

transform puede ser una cadena o un objeto.

Si transform es una cadena, define un remapeo del nombre del archivo. Debe contener un comodín * que será reemplazado con el nombre del archivo original (cualquier cosa antes del primer .).

Por ejemplo, si deseas que la extensión de todos tus archivos traducidos tenga .[locale].json en lugar de .json, puedes usar la siguiente configuración:

{
  "transform": "*.[locale].json"
}

Alternativamente, si transform es un objeto, debe contener las siguientes propiedades:

• match (opcional): Un patrón regex para coincidir con cadenas, soporta grupos de captura
• replace (requerido): Cadena o patrón regex para reemplazar la coincidencia

Ambos valores soportan grupos de captura regex y se mapean al nombre completo del archivo relativo del archivo de salida.

{
  "transform": {
    "match": "^(.*)$",
    "replace": "{locale}/$1"
  }
}

Por ejemplo, la configuración anterior hará que los archivos traducidos se guarden bajo un subdirectorio del idioma de destino.

Marcadores de Posición Especiales

La opción transform soporta varios marcadores de posición especiales que pueden usarse tanto en cadenas match como replace:

• {locale}: El marcador de posición del código de idioma que se comporta de manera diferente dependiendo del contexto:
  • En cadenas match: Reemplazado con el código de idioma predeterminado (ej., "en") para ayudar a identificar archivos fuente
  • En cadenas replace: Reemplazado con el código de idioma de destino (ej., "fr", "es") para los archivos de salida traducidos

Por ejemplo, si tu idioma predeterminado es "en" y estás traduciendo a "fr":

• Un patrón match de "content/{locale}/file.md" se convierte en "content/en/file.md"
• Un patrón replace de "content/{locale}/file.md" se convierte en "content/fr/file.md"

Adicionalmente, cualquier otra propiedad de getLocaleProperties() puede usarse como marcador de posición con el mismo comportamiento dependiente del contexto.

output

Esta clave se usa exclusivamente para archivos de General Translation, específicamente para guardar traducciones localmente. Si estás usando el CDN de GT, esta clave no es necesaria.

El valor debe ser una cadena que contenga un marcador de posición [locale] indicando la ubicación donde se guardarán las traducciones.

Por ejemplo, si deseas guardar tus traducciones al español en un archivo llamado ui.es.json en el directorio public/i18n, debes usar la siguiente cadena:

{
  "output": "public/i18n/[locale].json"
}

Tipo de Archivo: gt

Claves Soportadas

• output (Requerido)

Ejemplo

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
  }
}

Esta configuración hará que la herramienta CLI guarde tus traducciones al francés y español en el directorio public/i18n/[locale].json.

Por defecto, la herramienta CLI no publicará tus traducciones al CDN de GT con esta configuración.

Tipo de Archivo: json

Claves Soportadas

• include (Requerido)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["json_files/[locale]/**/*.json"],
      "exclude": ["json_files/[locale]/exclude/**/*.json"]
    }
  }
}

Digamos que el idioma predeterminado de tu proyecto es en, y quieres traducir tu proyecto a fr y es.

Con esta configuración, el CLI buscará todos los archivos JSON bajo el subdirectorio json_files/en/ y guardará los archivos traducidos en json_files/fr/ y json_files/es/.

Ignorará cualquier archivo en el subdirectorio json_files/en/exclude/.

Tipo de Archivo: yaml

Claves Soportadas

• include (Requerido)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "yaml": {
      "include": ["yaml_files/[locale]/**/*.yaml"],
      "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"]
    }
  }
}

Digamos que el idioma predeterminado de tu proyecto es en, y quieres traducir tu proyecto a fr y es.

Con esta configuración, el CLI buscará todos los archivos YAML bajo el subdirectorio yaml_files/en/ y guardará los archivos traducidos en yaml_files/fr/ y yaml_files/es/.

Ignorará cualquier archivo en el subdirectorio yaml_files/en/exclude/.

Tipo de Archivo: mdx

Claves Soportadas

• include (Requerido)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}

Esta configuración le dirá a la herramienta CLI que busque todos los archivos MDX bajo el directorio content/docs/en y guarde los archivos traducidos en el directorio content/docs/ja.

La clave transform hace que la extensión de los archivos traducidos se cambie a .ja.mdx.

Tipo de Archivo: md

Claves Soportadas

• include (Requerido)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "md": {
      "include": ["content/docs/[locale]/**/*.md"],
      "exclude": ["content/docs/[locale]/exclude/**/*.md"],
      "transform": "*.[locale].md"
    }
  }
}

Esta configuración le dirá a la herramienta CLI que busque todos los archivos MD bajo el directorio content/docs/en y guarde los archivos traducidos en el directorio content/docs/ja.

La clave transform hace que la extensión de los archivos traducidos se cambie a .ja.md.

Todos los archivos en el directorio content/docs/en/exclude serán ignorados.

Tipo de Archivo: js

Claves Soportadas

• include (Requerido)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "js": {
      "include": ["scripts/[locale]/**/*.js"]
    }
  }
}

Esta configuración le dirá a la herramienta CLI que busque todos los archivos JavaScript bajo el directorio scripts/en y guarde los archivos traducidos en los directorios scripts/fr y scripts/es.

La clave transform hace que la extensión de los archivos traducidos se cambie a .fr.js y .es.js respectivamente (desde .js).

Tipo de Archivo: ts

Claves Soportadas

• include (Requerido)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

{ 
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "ts": {
      "include": ["scripts/[locale]/**/*.ts"]
    }
  }
}

Esta configuración le dirá a la herramienta CLI que busque todos los archivos TypeScript bajo el directorio scripts/en y guarde los archivos traducidos en los directorios scripts/fr y scripts/es.

La clave transform hace que la extensión de los archivos traducidos se cambie a .fr.ts y .es.ts respectivamente (desde .ts).

Configuración de ejemplo

Analicemos un archivo de ejemplo gt.config.json:

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    },
    "json": {
      "include": ["resources/[locale]/**/*.json"],
      "exclude": ["resources/[locale]/exclude/**/*.json"]
    }
  }
}

En este ejemplo, estamos traduciendo los siguientes archivos con una sola llamada a gtx-cli translate:

• Todos los archivos MDX en el directorio content/docs/en.
• Todos los archivos JSON en el directorio resources/en (excluyendo cualquier archivo en el directorio resources/en/exclude).
• Todos los componentes en línea <T> en tu proyecto de React o Next.js.
• Tu archivo dictionary.[json|js|ts].

GT: Las traducciones se guardarán en public/i18n/es.json y public/i18n/fr.json. Estos archivos pueden cargarse usando loadTranslations().

MDX: Las traducciones se guardarán en los directorios content/docs/fr y content/docs/es. Las extensiones de los archivos cambiarán a .fr.mdx y .es.mdx respectivamente (desde .mdx).

JSON: Las traducciones se guardarán en los directorios resources/fr y resources/es.

Próximos pasos

Aprende cómo usar el comando init para generar este archivo de configuración.