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, entre otras, las siguientes propiedades:

• defaultLocale: El locale predeterminado de tu proyecto. Es el locale en el que está escrito tu contenido de origen. También actúa como contenido de respaldo predeterminado para tu proyecto (si usas gt-next o gt-react).

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

• files: Un objeto que contiene información sobre el contenido que quieres traducir.

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

• src: Matriz opcional de patrones glob de archivos para tus archivos fuente. De forma predeterminada, 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 del archivo del 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"
}

Alias de locale

Si quieres asignar un alias a un locale (p. ej., 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 con alias.

{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarín",
    }
  }
}

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 archivo:

• gt: archivos de General Translation.
• json: archivos JSON.
• yaml: archivos YAML.
• mdx: archivos de componentes 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 una matriz de patrones glob que coincidan con los files que quieres traducir.

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

La herramienta CLI guardará los archivos 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 valor de la clave exclude debe ser un array 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 salvedad de que el marcador [locale] es opcional. Si se proporciona, se reemplazará con el valor de defaultLocale.

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

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

Por ejemplo, si quieres que la extensión de todos tus archivos 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 regex para hacer coincidir cadenas; admite grupos de captura
• replace (obligatorio): Cadena o patrón de regex con el que reemplazar la coincidencia

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

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

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

Marcadores de posición especiales

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

• {locale}: Marcador del código de configuración regional que se comporta de forma diferente según el contexto:
  • En cadenas match: Se reemplaza por el código de configuración regional predeterminado (p. ej., "en") para ayudar a identificar los archivos de origen
  • En cadenas replace: Se reemplaza por el código de configuración regional de destino (p. ej., "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" pasa a ser "content/en/file.md"
• Un patrón replace de "content/{locale}/file.md" pasa a ser "content/fr/file.md"

Además, 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 de forma local. Si estás usando el GT CDN, esta clave no es necesaria.

El value debe ser una cadena que contenga el 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 CLI guarde tus traducciones al francés y al español en el directorio public/i18n/[locale].json.

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

Tipo de archivo: json

Claves admitidas

• 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"]
    }
  }
}

Supongamos que el locale predeterminado de tu proyecto es en y que quieres traducirlo 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 compatibles

• 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 traducirlo 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 admitidas

• 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 se 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 le indicará a la herramienta 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.

Se ignorarán todos los archivos del directorio content/docs/en/exclude.

Tipo de archivo: js

Claves compatibles

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

Ejemplo

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

Esta configuración indicará a la herramienta CLI que busque todos los archivos 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 de TypeScript en el directorio scripts/en y guarde los archivos traducidos en scripts/fr y scripts/es.

La clave transform hace que la extensión de los archivos traducidos pase a ser .fr.ts y .es.ts, respectivamente (en lugar de .ts).

Ejemplo de configuración

Analicemos un archivo gt.config.json a modo 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 archivos con una sola ejecución de gtx-cli translate:

• Todos los archivos MDX del directorio content/docs/en.
• Todos los archivos JSON del directorio resources/en (excluyendo los del directorio resources/en/exclude).
• Todos los componentes <T> en línea en tu proyecto 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 se pueden cargar con loadTranslations.

MDX: Las traducciones se guardarán en los directorios content/docs/fr y content/docs/es. Las extensiones de archivo 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.