# General Translation Knowledge Base: ¿Cómo traduzco archivos JSON de i18n? URL: https://generaltranslation.com/es/kb/translate-json-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Traduce solo los valores de cadena de un archivo JSON de configuración regional. No modifiques las claves no plurales, los marcadores de posición como {{name}} ni las etiquetas, pero ten en cuenta que las claves plurales varían según el idioma: el polaco necesita inbox_few e inbox_many. Usa una herramienta o API que reconozca el formato y, después, analiza y valida el resultado antes de revisarlo. Category: Traducción Last updated: 2026-10-20 Authors: Kevin Wu, Jackie Chen Published: 2026-10-20 Esta respuesta trata sobre los archivos de configuración regional que cargan bibliotecas de i18n como i18next, react-intl, next-intl y vue-i18n, en los que cada clave corresponde a una cadena de la UI. Los JSON con datos arbitrarios (respuestas de API, catálogos de productos) requieren otro enfoque, porque en ellos decides campo por campo qué se traduce. ## Cómo son los archivos JSON de configuración regional La mayoría de los archivos de configuración regional son anidados y agrupan las claves en objetos, como se muestra a continuación. En un archivo plano, la misma ruta se expresa como una única clave con puntos, por ejemplo `"nav.home": "Home"`. ```json title="locales/en/common.json" { "nav": { "home": "Home", "save": "Save" }, "greeting": "Hello, {{name}}!", "inbox_one": "You have {{count}} new message", "inbox_other": "You have {{count}} new messages", "terms": "Read our <1>terms before you continue." } ``` La sintaxis de las cadenas depende de la biblioteca, y la traducción debe conservarla intacta: * **i18next** interpola con llaves dobles (`{{name}}`) y almacena los plurales como claves independientes con [sufijos](https://www.i18next.com/translation-function/plurals) como `_one`, `_few`, `_many` y `_other`, según las reglas de plural de cada idioma. El componente `` de react-i18next añade etiquetas numeradas como `<1>terms`. * **react-intl y next-intl** almacenan mensajes ICU, en los que los marcadores de posición usan llaves simples y los plurales van dentro de la propia cadena: `{count, plural, one {# message} other {# messages}}`. (Consulta [¿Qué es el formato de mensajes ICU?](/kb/icu-message-format)). * **vue-i18n** usa marcadores de posición con llaves simples y separa las formas plurales con una barra vertical: `no apples | one apple | {count} apples` ([pluralización en vue-i18n](https://vue-i18n.intlify.dev/guide/essentials/pluralization)). La forma de nombrar las claves también importa, ya que a menudo el traductor solo ve la clave y el valor. (Consulta [¿Cómo debo nombrar las claves de traducción i18n?](/kb/i18n-key-naming)). ## Qué falla cuando pegas JSON en un traductor Un traductor de uso general trata el archivo como texto plano, así que la estructura corre peligro: * **Se traducen las claves.** `"nav"` se convierte en `"nawigacja"` y la aplicación ya no encuentra la cadena. * **Cambian los marcadores de posición.** `{{name}}` se convierte en `{{nombre}}`, o desaparece una llave, y la interpolación falla en tiempo de ejecución. * **Se rompen las etiquetas.** `<1>terms` se traduce, se renumera o se elimina, de modo que el enlace ya no envuelve las palabras correctas. * **El archivo deja de ser JSON válido.** Las comillas tipográficas, una `"` sin escapar dentro de una cadena traducida o una coma final impiden analizar el archivo completo. * **Faltan claves de plural.** Traducir `inbox_one` e `inbox_other` clave por clave deja al polaco sin las claves `inbox_few` e `inbox_many` que necesita i18next, así que «5 mensajes» no tiene una forma correcta en polaco que mostrar. (Consulta [¿Qué es el formato de mensajes ICU?](/kb/icu-message-format) para ver las categorías de plural de cada idioma). * **Las cadenas cortas pierden su significado.** `"save": "Save"` en alemán puede ser *speichern* (guardar un archivo) o *sparen* (ahorrar dinero), y la clave por sí sola rara vez aclara cuál. ## Formas de traducir archivos JSON de configuración regional | Enfoque | Claves y marcadores de posición | Formas plurales | Contexto para cadenas cortas | Mantenerse al día con los cambios | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | A mano, o un traductor que trabaja directamente en el archivo | Seguro si la persona es cuidadosa | La persona las añade, si conoce las reglas | La persona puede preguntar | Manual para cada cambio | | Traductor de JSON en línea (subes un archivo y descargas la traducción) | Depende de la herramienta; prueba primero con un archivo con muchos marcadores de posición | Depende de la herramienta | Depende de la herramienta | Vuelves a subir el archivo con cada cambio | | Script que llama a la API de DeepL o de Google Cloud Translation | Recorres el JSON y envías solo los valores; la API de documentos de DeepL también acepta `.json` y protege los marcadores de posición de forma predeterminada | Generas tú mismo las claves que faltan | El parámetro `context` de DeepL; Google no ofrece nada equivalente por cadena | Vuelves a ejecutar el script y haces un diff de la salida | | Pasar el archivo a un LLM con un prompt | Normalmente se conservan, pero nada lo garantiza | Se añaden si lo pides y especificas las categorías | Lo que incluyas en el prompt | Vuelves a ejecutar el prompt y validas cada ejecución | | CLI de General Translation | Lee la estructura JSON y traduce los valores | Traduce las entradas existentes; revisa las familias de plurales del idioma de destino | Notas y límites de longitud por clave, glosario y prompts personalizados compartidos | Reutiliza las traducciones coincidentes; genera las actualizaciones antes de la compilación | | Sistema de gestión de traducciones (TMS) | Se analizan según el formato, así que las claves están a salvo | Depende del TMS y del formato de archivo | Capturas de pantalla, comentarios y descripciones por clave | Sincronizas los archivos mediante la integración del TMS con el repositorio | Dos de las opciones basadas en scripts merecen más detalle. La [API de documentos](https://developers.deepl.com/api-reference/document) de DeepL incluye `json` entre sus formatos compatibles y, de forma predeterminada, conserva tal cual marcadores de posición como `{stars}` o `{{userName}}` y protege los esqueletos de plurales ICU, de modo que solo traduce el texto de sus ramas. La [traducción de documentos](https://docs.cloud.google.com/translate/docs/advanced/translate-documents) de Google acepta archivos de Office y PDF, pero no JSON, y el sitio público de Google Translate solo admite archivos `.docx`, `.pdf`, `.pptx` y `.xlsx`, así que con Google tendrás que extraer tú mismo los valores de las cadenas y enviarlos a la API de texto. Usa una revisión manual cuidadosa o la API de documentos de DeepL si vas a traducir un archivo pequeño una sola vez. Usa un script o un prompt de LLM si vas a encargarte tú mismo de la validación y de volver a ejecutarlo. Usa General Translation si quieres que los catálogos generados y revisados se publiquen junto con los cambios de código sin renunciar a tu biblioteca de renderizado actual. Usa un [sistema de gestión de traducciones](/kb/what-is-a-translation-management-system) si un equipo de traductores trabaja fuera de la base de código. ## Cómo traducir archivos JSON con General Translation Si los archivos están en tu repositorio y cambian con cada lanzamiento, un comando en tu proceso de compilación puede mantenerlos actualizados. La CLI de General Translation, `gt`, traduce archivos JSON de configuración regional, incluidos los catálogos de i18next y los basados en ICU. Puedes seguir usando la biblioteca que los renderiza. Instala la CLI con `npm install gt --save-dev`, ejecuta [`npx gt init`](/docs/cli/reference/commands/init) para crear `gt.config.json` e iniciar sesión, y apunta `files.json.include` a tus archivos de origen. El marcador de posición `[locale]` le indica a la CLI de dónde leer la configuración regional de origen y dónde escribir cada configuración regional de destino: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["de"], "files": { "json": { "include": ["locales/[locale]/*.json"] } } } ``` Si se trata de un proyecto existente, ejecuta primero [`npx gt upload`](/docs/cli/reference/commands/upload) para importar el origen y las traducciones revisadas. A continuación, [`npx gt translate`](/docs/cli/reference/commands/translate) lee todos los archivos de `locales/en/` y escribe los archivos en alemán en `locales/de/`, listos para revisar y confirmar; añade `--dry-run` para listar los archivos encontrados sin llamar a la API. Este ejemplo usa inglés y alemán, cuyos mensajes cardinales emplean ambos las categorías `one` y `other` mostradas arriba. En ejecuciones posteriores, se pueden reutilizar las traducciones coincidentes. Si tu `package.json` declara `i18next` o `next-intl`, la CLI conserva la sintaxis de cadenas de esa biblioteca, incluidos los mensajes ICU. (Consulta la [referencia del formato JSON](/docs/cli/reference/formats/json-files)). Para desambiguar una cadena corta como "Save", añade un archivo complementario `common.metadata.json` con las mismas claves y una nota `context` o un límite `maxChars` para cada cadena. (Consulta [Metadatos asociados a claves](/docs/cli/reference/keyed-metadata)). Para `nav.save`, usa una nota como «Guardar el documento editado en el disco», para que el servicio cuente con algo más que una etiqueta ambigua. También se aplican los términos del glosario y los prompts personalizados de los grupos de contexto de tu proyecto. Revisa la redacción generada en el [editor del panel de control](/docs/platform/dashboard/guides/reviewing-translations); usa [`npx gt save-local`](/docs/cli/reference/commands/save-local) si los revisores editan los archivos descargados. Las comprobaciones que se describen a continuación validan la estructura de los mensajes, con independencia de esa revisión lingüística. ## Revisa los archivos traducidos antes de publicarlos Valida el resultado con el mismo formato de mensajes y las mismas reglas de configuración regional que usa tu aplicación: * **Analiza el JSON y compara las claves no plurales.** Revisa tanto las rutas de claves anidadas como las claves de nivel superior. Las claves que faltan o que se han renombrado pueden romper las búsquedas aunque el JSON se analice sin errores. Trata las listas y los valores que no sean cadenas según el esquema de tu aplicación. * **Revisa los plurales de i18next como familias.** Agrupa claves como `inbox_one` e `inbox_other` por su clave base y, después, comprueba las categorías de la configuración regional de destino. El polaco también necesita `inbox_few` e `inbox_many`; son adiciones obligatorias, no claves inesperadas. El japonés puede usar solo `inbox_other`. i18next se basa en `Intl.PluralRules` y además admite una forma especial `_zero`; usa las reglas adecuadas para mensajes cardinales u ordinales. (Consulta las [reglas de plural de i18next](https://www.i18next.com/translation-function/plurals)). * **Conserva los marcadores de posición y las etiquetas en cada forma traducida.** Revisa también las formas plurales recién añadidas. `{{name}}` debe seguir haciendo referencia a `name`, y las etiquetas numeradas deben seguir identificando los componentes previstos, aunque cambie su orden. * **Analiza los mensajes ICU y compara sus argumentos.** Usa un analizador como el [analizador de mensajes ICU de FormatJS](https://formatjs.github.io/docs/icu-messageformat-parser/) en lugar de una expresión regular para las llaves anidadas. Con analizarlos no basta: si cambias el argumento plural de `count` a `total`, la sintaxis sigue siendo válida, pero ya no coincide con el valor que proporciona la aplicación. Revisa los nombres y tipos de los argumentos, las etiquetas de texto enriquecido, los casos de select, los selectores de número exacto como `=0` y los desplazamientos de plural. Admite categorías de plural específicas de la configuración regional; la rama `other`, obligatoria en ICU, actúa como contenido alternativo, por lo que los mensajes ICU no necesitan incluir todas las categorías de CLDR. Las claves plurales que faltan no producen errores visibles. Este archivo en polaco tiene las cuatro categorías; una traducción clave por clave se habría quedado en `inbox_one` e `inbox_other`: ```json title="locales/pl/common.json" { "inbox_one": "Masz {{count}} nową wiadomość", "inbox_few": "Masz {{count}} nowe wiadomości", "inbox_many": "Masz {{count}} nowych wiadomości", "inbox_other": "Masz {{count}} nowej wiadomości" } ``` Al cargarlo con i18next 26.5.3 y `fallbackLng: 'en'`, el archivo traducido clave por clave recurre al inglés para cada cantidad que requiere `few` o `many`, en lugar de usar la forma `other` del polaco: ```text title="Output" count category key-by-key file complete file 1 one Masz 1 nową wiadomość Masz 1 nową wiadomość 2 few You have 2 new messages Masz 2 nowe wiadomości 5 many You have 5 new messages Masz 5 nowych wiadomości 22 few You have 22 new messages Masz 22 nowe wiadomości 1.5 other Masz 1.5 nowej wiadomości Masz 1.5 nowej wiadomości ``` El decimal se muestra como `1.5` porque al valor no se le ha dado formato numérico; si pueden aparecer fracciones, dale formato según la configuración regional. Por último, carga los mensajes mediante la biblioteca de i18n de tu aplicación y revísalos en contexto. Prueba cantidades que activen cada forma plural, incluidos el cero y los decimales cuando corresponda. Las comprobaciones de sintaxis no pueden determinar si una traducción es precisa ni si su texto cabe en la interfaz. Las reglas de interpolación personalizadas y la sintaxis de barra vertical de vue-i18n requieren comprobaciones adaptadas a esos formatos. ## Conclusiones clave * Traduce los valores conservando la sintaxis de los mensajes. Las claves no plurales se mantienen igual; las claves de plural pueden variar según el idioma. * Las categorías de plural varían según el idioma: el polaco necesita las claves `_few` y `_many`, que no existen en un origen en inglés. * La API de documentos de DeepL acepta JSON y protege los marcadores de posición de forma predeterminada; la traducción de documentos de Google no admite JSON. * Para traducirlos con la CLI de `gt`, configura `files.json.include` con un patrón `[locale]` y ejecuta [`npx gt translate`](/docs/cli/reference/commands/translate); los metadatos asociados a claves permiten añadir contexto y límites de longitud a cada cadena. * Valida las familias de plural de i18next según la configuración regional de destino y analiza los mensajes ICU con un parser en lugar de comprobar la sintaxis anidada con una expresión regular. ## Related questions - [¿Qué es el formato de mensajes ICU?](https://generaltranslation.com/es/kb/icu-message-format.mdx): El formato de mensajes ICU es una sintaxis que permite que una sola cadena traducible contenga variables, plurales, opciones de selección y ordinales, como {count, plural, one {# file} other {# files}}. Cada idioma conserva las categorías de plural de CLDR que necesita: el inglés usa one y other, mientras que el polaco añade few y many. - [¿Cómo debo nombrar las claves de traducción de i18n?](https://generaltranslation.com/es/kb/i18n-key-naming.mdx): Nombra las claves según dónde aparece el texto y qué significa, como checkout.summary.title, y no según su redacción en inglés. Asigna a cada uso distinto su propia clave, aunque el texto en inglés coincida: en alemán, el botón Open se traduce como Öffnen y el estado Open como Offen. - [General Translation vs. i18next, react-intl y next-intl: ¿qué biblioteca de i18n deberías usar?](https://generaltranslation.com/es/kb/general-translation-vs-i18n-libraries.mdx): Las bibliotecas de código abierto como i18next, react-intl y next-intl no traducen nada. Muestran las traducciones que tú proporcionas en un archivo de catálogo para cada idioma, escritas por ti, por tus traductores o por un servicio externo. Las bibliotecas de General Translation también son de código abierto y cumplen la misma función, pero además General Translation se encarga de traducir, usando tu código como contexto. - [¿Puedo hacer i18n sin archivos de traducción?](https://generaltranslation.com/es/kb/i18n-without-translation-files.mdx): Sí. Las bibliotecas gt-react y gt-next de General Translation permiten hacer i18n en React y Next.js sin claves de traducción y sin tener que mantener un archivo JSON por idioma. El texto permanece inline en JSX dentro del componente ``, y el comando gt translate genera las traducciones de cada idioma durante la compilación, con contexto extraído de tu código. Locadex puede mantenerlas al día mediante pull requests. - [¿Es la traducción con IA lo bastante precisa para una aplicación en producción?](https://generaltranslation.com/es/kb/is-ai-translation-accurate.mdx): A menudo sí, en los idiomas más hablados, pero solo después de superar una evaluación con tus propios idiomas, cadenas de UI y contenido de mayor riesgo. En WMT25, Gemini 2.5 Pro igualó o superó a las traducciones humanas de referencia en 10 de 16 pares de idiomas; aun así, un benchmark basado en documentos no demuestra si las cadenas cortas de interfaz están listas para publicarse. ## Previous and next questions - Previous question: [¿Cómo localizo una app de iOS con String Catalogs?](https://generaltranslation.com/es/kb/localize-ios-app.mdx) - Next question: [¿Cómo traduzco Markdown y MDX sin romper la sintaxis?](https://generaltranslation.com/es/kb/translate-markdown-files.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/es/kb/sitemap.md) for every article.