Descripción general

El archivo gt.config.json se usa para configurar la GT de tu proyecto. Debe ubicarse en la raíz del proyecto.

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

Configuración

El archivo gt.config.json acepta las siguientes propiedades, entre otras:

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

• locales: Un arreglo de locales para tu proyecto. Son los locales a los que quieres traducir tu proyecto. Consulta las locales compatibles para obtener más información. Si usas gt-next o gt-react, estos también son los locales que tu app admite.

• files: Objeto que contiene información sobre el contenido que deseas traducir.

• stageTranslations: Indicador booleano opcional que señala si tu proyecto está configurado para usar revisión humana.

• src: Arreglo opcional de patrones glob para tus files de origen. De forma predeterminada, establecido 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 del archivo de diccionario.

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

Aquí tienes un esquema básico 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"
}

Alias de locale

Si quieres crear un alias para un locale (por ejemplo, cn en lugar de zh), puedes especificar un mapeo personalizado en el archivo gt.config.json.

{
  "customMapping": {
    "cn": {
      "code": "zh",
    }
  }
}

También puedes especificar distintos atributos para el locale al que asignaste un alias.

{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarin",
    }
  }
}

files

Tipos de archivos compatibles

files debe contener una clave por cada tipo de archivo que quieras traducir. Puedes configurar tu proyecto para combinar distintos tipos de archivos y que todos se traduzcan. Actualmente admitimos los siguientes tipos de archivos:

• gt: files de General Translation.
• json: files JSON.
• yaml: files YAML.
• mdx: files de componentes Markdown (MDX).
• md: files Markdown (MD).
• js: files JavaScript.
• ts: files 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 value de la clave include debe ser un arreglo de patrones glob que coincidan con los files que quieres translate.

Debes usar el marcador [locale] en tus patrones glob para garantizar que los files de origen se encuentren correctamente y que los files traducidos se guarden en la ubicación correcta. La herramienta de CLI reemplazará el marcador [locale] con el defaultLocale value al buscar files traducibles.

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

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

exclude

Si se utiliza, el value de la clave exclude debe ser un arreglo de patrones glob que coincidan con los files que deseas excluir de la traducción.

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

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

Si quieres excluir files de la traducción para todos los locales, puedes usar el marcador [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 reasignado del name del archivo. Debe contener un comodín * que se reemplazará por el name original del archivo (todo lo anterior al primer .).

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

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

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

• match (opcional): Un patrón de expresiones regulares para hacer coincidir cadenas; admite grupos de captura
• replace (obligatorio): Cadena o patrón de expresiones regulares con el que reemplazar la coincidencia

Ambos valores admiten grupos de captura de expresiones regulares y se mapean al nombre de archivo relativo completo del archivo de salida.

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

Por ejemplo, la configuración anterior hará que los files traducidos se guarden en un subdirectorio del locale de destino.

Marcadores de posición especiales

La opción transform admite varios marcadores de posición especiales que se pueden usar tanto en las cadenas match como replace:

• {locale}: El marcador de posición del código de configuración regional que se comporta de manera diferente según el contexto:
  • En cadenas match: Se reemplaza con el código de configuración regional predeterminado (por ejemplo, "en") para ayudar a identificar los archivos de origen
  • En cadenas replace: Se reemplaza con el código de configuración regional de destino (por ejemplo, "fr", "es") para los archivos de salida traducidos

Por ejemplo, si tu configuración regional predeterminada 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"

Además, cualquier otra propiedad de getLocaleProperties se puede usar como marcador de posición con el mismo comportamiento dependiente del contexto.

output

Esta clave se usa exclusivamente para files de General Translation, específicamente para guardar traducciones localmente. Si estás usando el GT CDN (Red de distribución de contenido), esta clave no es necesaria.

El value debe ser una cadena que contenga un marcador [locale] que indique la ubicación donde se guardarán las traducciones.

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

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

Tipo de archivo: gt

Claves admitidas

• output (Obligatorio)

Ejemplo

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

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

De forma predeterminada, la herramienta de CLI no publicará tus traducciones en el GT CDN con esta configuración.

Tipo de archivo: json

Claves compatibles

• include (Obligatorio)
• 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 locale predeterminado de tu proyecto es en, y quieres traducir tu proyecto a fr y es.

Con esta configuración, la CLI buscará todos los archivos JSON en 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 admitidas

• include (Obligatorio)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

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

Supongamos que el locale predeterminado de tu proyecto es en y quieres traducir tu proyecto a fr y es.

Con esta configuración, la CLI buscará todos los archivos YAML en 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 compatibles

• include (Obligatorio)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

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

Esta configuración indicará a la herramienta CLI que busque todos los archivos MDX en 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 cambie a .ja.mdx.

Tipo de archivo: md

Claves admitidas

• include (Obligatorio)
• 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 indicará a la herramienta de CLI que busque todos los archivos MD en 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 cambie a .ja.md.

Todos los archivos en el directorio content/docs/en/exclude se ignorarán.

Tipo de archivo: js

Claves admitidas

• include (Obligatorio)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

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

Esta configuración le indicará a la herramienta CLI que busque todos los archivos de JavaScript en 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 cambie a .fr.js y .es.js, respectivamente (a partir de .js).

Tipo de archivo: ts

Claves admitidas

• include (Obligatorio)
• exclude (Opcional)
• transform (Opcional)

Ejemplo

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

Esta configuración indicará a la herramienta CLI que busque todos los archivos TypeScript dentro del 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 cambie a .fr.ts y .es.ts, respectivamente (a partir de .ts).

Ejemplo de configuración

Analicemos un archivo gt.config.json de ejemplo:

{
  "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, traducimos los siguientes files con una sola llamada a gtx-cli translate:

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

GT: Las traducciones se guardarán en public/i18n/es.json y public/i18n/fr.json. Estos files se pueden cargar usando loadTranslations.

MDX: Las traducciones se guardarán en los directorios content/docs/fr y content/docs/es. Las extensiones de file se 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 a usar el comando init para generar este archivo de configuración.