# General Translation Knowledge Base: ¿Cómo traduzco archivos de configuración regional YAML? URL: https://generaltranslation.com/es/kb/translate-yaml-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Traduce solo los valores de cadena y deja intactas las claves, los marcadores de posición como %{name} o {{name}} y las anclas. Pon entre comillas los valores que contengan dos puntos o empiecen por % o {, define la raíz de configuración regional o el nombre de cada archivo y añade las claves de plural que necesite el idioma de destino. La CLI de General Translation traduce los valores YAML en el mismo documento y no modifica las claves. Category: Traducción Last updated: 2026-10-28 Authors: General Translation Team Published: 2026-10-28 Un archivo de configuración regional YAML asocia claves a cadenas visibles para el usuario, con un archivo (o una clave de nivel superior) por idioma. Traducirlo consiste en sustituir los valores de cadena sin alterar las claves, los marcadores de posición ni la estructura del archivo, que deben quedar exactamente como los espera el framework. En YAML esto es más delicado que en JSON: unos dos puntos sin comillas o un `%` al principio rompen el análisis, y `no` puede interpretarse como un booleano, así que una traducción correcta puede acabar generando un archivo que tu aplicación rechaza o interpreta mal. ## Estructuras comunes de configuración regional en YAML Cada framework ubica el idioma en un lugar distinto y usa su propia sintaxis de marcadores de posición, y los archivos traducidos deben seguir esas mismas reglas: | Framework | Archivo de origen | Dónde va el idioma | Marcadores de posición | Plurales | | -------------------------------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------- | -------------------------------------------- | --------------------------------------------------------- | | [Rails I18n](https://guides.rubyonrails.org/i18n.html) | `config/locales/en.yml` | Clave de nivel superior (`en:`) | `%{name}` | Claves `one` y `other`; más con rails-i18n | | [Symfony](https://symfony.com/doc/current/translation.html#translation-resource-file-names-and-locations) | `translations/messages.en.yaml` | Nombre de archivo (`domain.locale.yaml`) | `%name%`, o `{name}` en archivos `+intl-icu` | Plurales ICU dentro de la cadena | | [Hugo](https://gohugo.io/functions/lang/translate/#translation-tables) | `i18n/en.yaml` | Nombre de archivo | Plantillas de Go como `{{ . }}` | Claves CLDR (`one`, `few`, `many`, `other`) | | i18next con [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend) | `locales/en/common.yml` | Directorio | `{{name}}` | Claves con sufijo, como `_one` y `_other` | | vue-i18n con [unplugin-vue-i18n](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) | `locales/en.yaml` | Nombre de archivo | `{name}` | Formas separadas por barras verticales en una sola cadena | Rails es el más estricto en cuanto a estructura. La [guía de Rails](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale) carga todos los archivos `.yml` y `.rb` de `config/locales`, y en cada archivo «la clave de nivel superior es la configuración regional». Un archivo en español debe empezar con `es:`, independientemente de cómo se llame. ## Trampas de YAML que rompen los archivos traducidos Este es un archivo de Rails escrito para que todos los valores sobrevivan a la traducción: ```yaml title="config/locales/en.yml" en: checkout: title: "Note: prices include VAT" joined: "%{name} joined your team" confirm_no: "No" terms: | By paying, you agree to our terms. Refunds take 5 to 7 days. items: one: "%{count} item" other: "%{count} items" ``` Cada línea evita un fallo habitual: * **Dos puntos.** `title: Note: prices include VAT` sin comillas es un error de sintaxis, y una traducción puede añadir dos puntos que el texto en inglés no tenía. * **Valores que empiezan con un carácter indicador.** Un valor sin comillas no puede empezar con `%`, `{`, `[`, `@` ni una comilla invertida. `joined: %{name} joined your team` no se puede analizar, y `{{name}} joined` se interpreta como el inicio de un mapeo. El orden de las palabras cambia al traducir, por lo que un marcador de posición que en inglés estaba en mitad de la frase a menudo acaba al principio. Por este motivo, la propia documentación de Hugo entrecomilla `'{{ . }} day'`. * **Booleanos.** El analizador sintáctico de YAML de Ruby sigue YAML 1.1, así que `yes`, `no`, `on` y `off` sin comillas se convierten en `true` y `false`; los analizadores de YAML 1.2, incluida la mayoría de las herramientas de JavaScript, los leen como cadenas. La guía de Rails indica que [estas claves deben escaparse](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale), y lo mismo vale para los valores. Incluso un archivo noruego cuya raíz es `no:` se carga en Ruby bajo la clave `false`. * **Escalares de bloque.** `|` conserva los saltos de línea y `>` los convierte en espacios. Las líneas traducidas deben mantener la sangría del bloque; de lo contrario, el valor termina antes de tiempo o el archivo ya no se puede analizar. * **Anclas y alias.** `&name` define un bloque y `*name` lo reutiliza, por lo que modificar un valor anclado modifica todos sus alias. Rails los carga, pero unplugin-vue-i18n indica que sus recursos YAML [no admiten alias](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n), así que comprueba tu cargador antes de usarlos. Con las líneas `title` y `joined` sin comillas, cada una en su propio archivo, el analizador sintáctico de Ruby (Ruby 2.6, Psych 3.1) rechaza ambas antes de que Rails llegue a leer una sola clave: ```text title="Output" unquoted-colon.yml: mapping values are not allowed in this context at line 3 column 16 unquoted-placeholder.yml: found character that cannot start any token while scanning for the next token at line 3 column 13 ``` Entrecomillar todos los valores es la regla más sencilla: una cadena entre comillas dobles siempre es una cadena, y `%{name}`, los dos puntos y `No` se conservan como texto. ### Las claves de plural varían según el idioma El inglés usa `one` y `other`, pero el ruso y el polaco también necesitan `few` y `many`. Si faltan claves, no se produce ningún error. Con el backend de pluralización de la gema i18n y una regla de pluralización para el ruso como la que incluye rails-i18n, un archivo traducido clave por clave desde el inglés recurre silenciosamente a `other` en todas las cantidades que requieren `few`. Los dos archivos en ruso que aparecen a continuación contienen traducciones de General Translation: ```text title="Output" count key-by-key (one, other) complete (one, few, many, other) 1 У вас 1 непрочитанное сообщение. У вас 1 непрочитанное сообщение. 3 У вас 3 непрочитанных сообщений. У вас 3 непрочитанных сообщения. 5 У вас 5 непрочитанных сообщений. У вас 5 непрочитанных сообщений. 22 У вас 22 непрочитанных сообщений. У вас 22 непрочитанных сообщения. ``` La [guía de Rails](https://guides.rubyonrails.org/i18n.html#locale-specific-rules) señala que, de forma predeterminada, solo se aplican las reglas de plural del inglés; las del resto de idiomas las aporta el backend `Pluralization` de I18n o la gema rails-i18n. Las tablas de traducción de Hugo usan las mismas categorías de CLDR, desde `zero` hasta `other`. ### Hay que cambiar la raíz de la configuración regional En Rails, un archivo traducido que sigue empezando por `en:` no da error. Se carga como inglés: en una prueba con la gema i18n, un archivo en español que conservaba la raíz `en:` sustituyó el título en inglés por el texto en español, e `I18n.t` para `es` devolvió un mensaje de traducción faltante. Cambia el nombre de la raíz en cada archivo traducido y mantén `config.i18n.available_locales` sincronizado. ## Formas de traducir archivos de configuración regional YAML | Enfoque | Claves y marcadores de posición | Claves de plural | Contexto para cadenas cortas | Mantenerse al día con los cambios | | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------- | | A mano | Seguro si el traductor conoce YAML | Se agregan si el traductor conoce las reglas del idioma | El traductor puede preguntar | Manual en cada cambio | | [i18n-tasks](https://github.com/glebm/i18n-tasks) `translate-missing` (Rails) con Google Translate, DeepL u OpenAI | Sustituye `%{...}` por tokens antes del envío | `missing` informa de las formas plurales que faltan cuando se cargan las reglas de rails-i18n | Opciones y prompts propios de cada backend | Completa las claves faltantes; el texto en inglés editado no se vuelve a traducir | | Un sistema de gestión de traducciones (TMS) | Se analizan sintácticamente según el formato | Depende del TMS | Capturas de pantalla, comentarios, glosario | Sincronización con el repositorio o intercambio de archivos | | Un script de LLM que procese el archivo | Normalmente se conservan, pero nada garantiza el entrecomillado | Solo se agregan si las pides | Lo que incluyas en el prompt | Volver a ejecutarlo y validar cada vez | | [CLI de General Translation](/docs/cli/reference/formats/yaml-files) | Traduce solo los valores de cadena; las claves no cambian | Traduce las claves de tu archivo de origen | Glosario, prompts personalizados, metadatos por clave | Reutiliza las traducciones sin cambios en cada ejecución | Edita a mano si se trata de uno o dos archivos pequeños. Usa i18n-tasks si una app de Rails necesita detectar claves faltantes y te basta con rellenar los huecos con traducción automática que revises tú mismo. (Consulta [General Translation vs. i18n-tasks](/kb/general-translation-vs-i18n-tasks) para ver cómo se complementan). Usa un [TMS](/kb/what-is-a-translation-management-system) si los archivos están a cargo de traductores. Usa General Translation si quieres que cada archivo de configuración regional se regenere a medida que cambia el inglés, con una terminología común en tu app, tu documentación y tu sitio de marketing. ## Traducir archivos YAML con General Translation La CLI de General Translation, `gt`, traduce archivos `.yaml` y `.yml` mediante una entrada `yaml` en `gt.config.json`. El marcador de posición `[locale]` indica dónde va el idioma, así que los formatos que incluyen la configuración regional en el nombre del archivo funcionan sin cambios. En Symfony, `translations/*.[locale].yaml` asigna `messages+intl-icu.en.yaml` a `messages+intl-icu.fr.yaml`; en Hugo: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["de", "pt-BR"], "files": { "yaml": { "include": ["i18n/[locale].yaml"] } } } ``` Según lo comprobado con `gt` 2.26.11, la resolución de rutas de la CLI asigna `i18n/en.yaml` a `i18n/de.yaml` y `i18n/pt-BR.yaml`, lo que coincide con los nombres de archivo basados en etiquetas de idioma de Hugo. Inicia sesión con [`npx gt login`](/docs/cli/reference/commands/login) y configura un ID del proyecto ([credenciales de la CLI](/docs/cli/guides/configuring#credentials)), importa las traducciones que ya tengas con [`npx gt upload`](/docs/cli/reference/commands/upload) y, a continuación, ejecuta [`npx gt translate`](/docs/cli/reference/commands/translate). General Translation traduce los valores de cadena y deja todo lo demás intacto: las claves, los números, los booleanos y los comentarios se conservan, y un bloque con ancla se traduce una sola vez mientras sus alias siguen apuntando a él. Por eso, algunos detalles propios del framework siguen corriendo de tu cuenta: * **Raíces de configuración regional de Rails.** La CLI no renombra claves, ni siquiera la `en:` de nivel superior, y la opción [`transform`](/docs/cli/reference/config#files) renombra los archivos de salida, no las claves. Mantén archivos de trabajo sin raíz, como `translations/en.yml`, para la CLI y añade la raíz de configuración regional al exportarlos a `config/locales`. (Consulta [General Translation vs. Rails I18n](/kb/general-translation-vs-rails-i18n) para ver un breve script de exportación). * **Claves de plural.** La CLI traduce las claves de plural que contiene tu origen, por lo que un archivo en ruso generado a partir de un origen en inglés con `one`/`other` tendrá `one` y `other`. Ejecuta `i18n-tasks missing` con rails-i18n cargado para localizar las claves `few` y `many` que aún faltan. * **`yes`, `no`, `on` y `off` sin comillas.** General Translation analiza YAML según las reglas de la versión 1.2, en las que estos valores son cadenas, así que se traducen como texto. Ponlos entre comillas en tu origen, como harías de todos modos en Rails. * **Sintaxis de la biblioteca.** La sintaxis de cadenas personalizada, como los mensajes ICU, es compatible con `i18next` y `next-intl`; con otras bibliotecas, revisa las cadenas con sintaxis personalizada después de la primera ejecución. Para desambiguar una cadena corta como «Guardar», añade un archivo `.metadata.yaml` complementario con una nota `context` o un límite `maxChars` por clave ([metadatos asociados a claves](/docs/cli/reference/formats/yaml-files#metadata)). Un glosario y prompts personalizados en un [grupo de contexto](/docs/platform/dashboard/guides/defining-context-for-translations) mantienen la coherencia de los términos del producto en tus catálogos YAML y en todos los demás proyectos del grupo, y los revisores pueden [editar traducciones en el panel de control](/docs/platform/dashboard/guides/reviewing-translations). Si alguien edita un archivo traducido en local, ejecuta [`npx gt save-local`](/docs/cli/reference/commands/save-local) antes de la siguiente ejecución para que no se sobrescriba. Después de cada ejecución, carga los archivos como lo hace tu aplicación: `i18n-tasks missing` e `i18n-tasks check-consistent-interpolations` para Rails, `lint:translations` para Symfony y una compilación para Hugo. (Consulta [General Translation vs. Symfony Translation](/kb/general-translation-vs-symfony-translation) para la configuración inicial de Symfony y [¿Cómo traduzco archivos JSON de i18n?](/kb/translate-json-files) si tus catálogos están en JSON). ## Preguntas frecuentes ### ¿Debo poner entre comillas todos los valores en un archivo de configuración regional YAML? Poner todos los valores entre comillas es la práctica más segura. Un valor entre comillas dobles siempre es una cadena, así que ni los dos puntos, ni un `%{name}` al principio, ni palabras como `No` pueden alterar la forma en que se analiza el archivo, ni antes ni después de la traducción. ### ¿Por qué mi aplicación Rails muestra "translation missing" en un idioma que ya traduje? Primero, revisa la clave de nivel superior del archivo. Si la raíz del archivo sigue siendo `en:`, se carga como inglés y la nueva configuración regional se queda sin claves. Comprueba también que la configuración regional figure en `config.i18n.available_locales`. ### ¿Puedo usar anclas y alias en los archivos de configuración regional? Rails los carga, pero algunos cargadores no, como unplugin-vue-i18n para vue-i18n. Al traducir un valor con ancla, cambian todos los alias que apuntan a él, así que úsalos solo para textos que deban ser idénticos en todas partes. ## Conclusiones clave * Traduce solo los valores; las claves, los marcadores de posición como `%{name}` y `{{name}}`, y la sangría de los bloques se quedan tal cual. * Pon entre comillas los valores que contengan dos puntos, que empiecen por `%` o `{`, o que sean palabras como `yes`, `no`, `on` y `off`; si no llevan comillas, Ruby los interpreta como booleanos. * El ruso y el polaco necesitan claves `few` y `many` que un origen en inglés no tiene, y si faltan, Rails recurre a `other` sin avisar. * Cada archivo de Rails necesita su propia raíz de configuración regional; un archivo en español con raíz `en:` se carga como inglés. * La CLI de General Translation traduce los valores de cadena de YAML con `"yaml": { "include": [...] }` y [`npx gt translate`](/docs/cli/reference/commands/translate), y conserva las claves, los comentarios y las anclas; las raíces de Rails y las claves de plural que falten siguen siendo responsabilidad tuya. ## Related questions - [General Translation vs. Rails I18n: ¿necesitas ambos?](https://generaltranslation.com/es/kb/general-translation-vs-rails-i18n.mdx): Rails I18n busca mensajes y da formato a fechas y números. General Translation genera las traducciones, las mantiene al día a medida que cambia tu texto en inglés y ofrece a tu equipo un panel de control para revisarlas. Usa ambos para publicar catálogos de Rails traducidos en cada lanzamiento. - [General Translation vs. i18n-tasks: ¿cuál deberías usar?](https://generaltranslation.com/es/kb/general-translation-vs-i18n-tasks.mdx): i18n-tasks es una gema de Ruby que detecta claves de Rails I18n faltantes y sin usar, ordena los archivos de configuración regional y puede completar las claves faltantes mediante Google Translate, DeepL, OpenAI, Yandex o watsonx. General Translation traduce archivos de configuración regional completos con tu glosario, tus prompts personalizados y la revisión en el panel de control. Cumplen funciones distintas, y muchos equipos pueden usar ambas. - [General Translation vs. Symfony Translation: ¿cuál deberías usar?](https://generaltranslation.com/es/kb/general-translation-vs-symfony-translation.mdx): Symfony Translation renderiza mensajes en PHP y Twig. General Translation traduce sus catálogos YAML en CI, los mantiene al día a medida que cambia tu contenido de origen y ofrece a los revisores un panel de control para editarlos. Conserva el renderizado de Symfony y añade traducción automatizada a tu flujo de trabajo de lanzamiento. - [¿Cómo traduzco archivos JSON de i18n?](https://generaltranslation.com/es/kb/translate-json-files.mdx): 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. - [¿Cómo traduzco archivos PO y POT?](https://generaltranslation.com/es/kb/translate-po-files.mdx): Rellena cada msgstr, incluidas todas las formas plurales que pide la cabecera Plural-Forms, y deja msgid, msgctxt y los marcadores de posición sin cambios. Ejecuta msgfmt --check para verificar las cabeceras, el número de formas plurales y los marcadores de posición en las entradas con una opción de formato, y comprueba por separado que ningún msgstr esté vacío. La CLI de General Translation genera un archivo PO traducido para cada idioma a partir de tu plantilla POT. ## Previous and next questions - Previous question: [¿Cómo traduzco archivos .resx en una aplicación .NET?](https://generaltranslation.com/es/kb/translate-resx-files.mdx) - Next question: [¿Cómo traduzco archivos PO y POT?](https://generaltranslation.com/es/kb/translate-po-files.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/es/kb/sitemap.md) for every article.