La CLI de Lingo.dev traduce los catálogos de cadenas de Xcode (.xcstrings) a través de un motor de localización configurado. Los catálogos de cadenas son el formato moderno de localización de Apple, introducido en Xcode 15, que almacena todos los idiomas en un único archivo JSON. La CLI modifica este archivo directamente, sin necesidad de directorios por idioma.
Esta guía te acompaña en todo el proceso de localización de una app iOS: configurar la CLI, traducir en local y automatizar con la GitHub App para que las traducciones se publiquen con cada push.
Repositorio de demostración
Clona o haz fork de lingodotdev/ios-app-localization-example para seguir el tutorial. El repositorio incluye un proyecto de Xcode totalmente funcional con String Catalogs y una configuración de la CLI de Lingo.dev.
Cómo funcionan los catálogos de cadenas#
Antes de Xcode 15, la localización en iOS obligaba a gestionar archivos .strings y .stringsdict independientes en distintos directorios [locale].lproj/. Los catálogos de cadenas sustituyen todo eso por un único archivo Localizable.xcstrings que Xcode mantiene automáticamente.
Cuando marcas una cadena como localizable en SwiftUI o UIKit, Xcode la detecta durante la compilación y añade una entrada al catálogo de cadenas. Cada entrada registra la cadena de origen, sus traducciones para cada idioma configurado y un campo de comentario opcional que aporta contexto a los traductores.
| Aspecto | .strings heredado | Catálogos de cadenas .xcstrings |
|---|---|---|
| Número de archivos | Uno por idioma y por tabla | Un solo archivo para todos los idiomas |
| Formato | Texto clave-valor | JSON estructurado |
| Compatibilidad con plurales | Archivo .stringsdict independiente | Reglas de plural integradas |
| Integración con Xcode | Exportación e importación manuales | Detección automática |
| Notas para traductores | No compatible | Campo de comentario por entrada |
La CLI detecta el formato .xcstrings a partir de la extensión del archivo, procesa esta estructura JSON, traduce cada entrada mediante el motor de localización y escribe las traducciones de nuevo en el mismo archivo, conservando comentarios, reglas de plural y metadatos.
Requisitos previos#
Crea un motor de localización
Cada traducción hace pasar el contenido por un motor de localización, la configuración que determina qué modelo de LLM, glosario, voz de marca y reglas se aplican. Crea uno en el panel de Lingo.dev y genera una clave de API.
Comprueba Node.js
La CLI requiere Node.js 22 o superior:
node -vActiva la localización en Xcode
En tu proyecto de Xcode, ve a Project Settings > Info > Localizations y añade tus idiomas de destino. Xcode crea las entradas del catálogo de cadenas para cada idioma que añadas. Consulta la documentación sobre localización de Apple para más detalles.
Instala y configura la CLI#
Instala la CLI, autentícate y configura el proyecto. Consulta la guía de inicio rápido para ver el proceso completo.
npm install -g @lingo.dev/cli
lingo loginEjecuta lingo init en la raíz del proyecto y responde a las indicaciones (idioma de origen, idiomas de destino y el patrón de archivos que apunta a tu String Catalog). Después, ejecuta lingo link para vincular el proyecto a tu organización y motor. Entre ambos, crearán un .lingo/config.json:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "MyApp/Localizable.xcstrings" }]
}Haz commit de .lingo/config.json: es la fuente de verdad de lo que se traduce. El formato .xcstrings se detecta a partir de la extensión del archivo. Como String Catalogs almacena todos los idiomas en un único archivo, no hace falta ningún marcador de idioma en el patrón: la CLI lee las entradas del idioma de origen y escribe todos los idiomas de destino de nuevo en ese mismo archivo. Consulta la Referencia de configuración para ver el esquema completo.
Varios catálogos de cadenas
Si tu proyecto utiliza varios archivos de String Catalog (por ejemplo, uno por target de framework), añade una entrada files para cada uno:
{
"files": [
{ "pattern": "MyApp/Localizable.xcstrings" },
{ "pattern": "MyAppWidgets/Localizable.xcstrings" }
]
}Traduce en local#
Desde la raíz del proyecto, ejecuta la primera traducción:
lingo push --backfill-missingLa CLI lee tu String Catalog, traduce cada entrada pendiente mediante tu motor de localización, espera a que termine la ejecución y escribe los resultados de nuevo en el archivo .xcstrings. Abre el archivo en Xcode para ver las traducciones completadas en cada idioma configurado.
Después de editar las cadenas de origen, un simple lingo push traduce solo el delta: las entradas cuyo texto de origen no ha cambiado se omiten en el servidor y se rastrean mediante el lockfile:
lingo pushNotas para traductores#
Los catálogos de cadenas admiten un campo de comentario por entrada que la CLI incluye en las solicitudes de traducción. Estos comentarios aportan contexto al motor de localización: aclaran términos ambiguos, especifican el tono o describen dónde aparece una cadena en la interfaz.
En Xcode, selecciona una cadena en el editor del catálogo de cadenas y añade un comentario en el panel del inspector. El comentario se guarda en el JSON .xcstrings:
{
"sourceLanguage": "en",
"strings": {
"Set": {
"comment": "Refers to a collection of items, not the verb",
"localizations": { }
}
}
}La CLI envía este comentario junto con la cadena, guiando al modelo hacia la interpretación correcta. "Set" sin contexto podría traducirse como un verbo en muchos idiomas; el comentario elimina esa ambigüedad. Consulta Translator Notes para ver más patrones.
Plurales#
Los catálogos de cadenas gestionan de forma nativa las formas plurales mediante las reglas de plural de CLDR. Cuando defines una variación plural en Xcode, el catálogo de cadenas almacena reglas para cada categoría plural (zero, one, two, few, many, other) que requiere el idioma de destino.
La CLI conserva esta estructura durante la traducción y genera las categorías plurales correctas para cada idioma de destino. El inglés usa dos categorías (one y other), pero el árabe necesita seis, el polaco cuatro y el japonés una. El motor de localización gestiona estas diferencias automáticamente.
Automatiza con la GitHub App#
Instala la GitHub App de Lingo.dev en tu repositorio para una Localización continua, sin runners de CI, secretos de API key ni lockfiles que gestionar. Una vez instalada y apuntando a tu .lingo/config.json (con su engineId), reacciona automáticamente a pushes y pull requests: detecta las cadenas de origen modificadas, las traduce con tu motor y hace commit del .xcstrings actualizado en la rama o abre una pull request.
¿Prefieres ejecutarlo por tu cuenta?
También puedes ejecutar lingo push desde tu propio job de CI (en cualquier runner con Node.js) y hacer commit de los resultados, autenticándote con LINGO_API_KEY. Consulta Flujos de trabajo de CI/CD para ver los patrones basados en runners.
Verifica antes de desplegar#
Usa lingo check como control previo al despliegue para asegurarte de que no lleguen cadenas sin traducir a producción. Informa de las traducciones que faltan o están desactualizadas y finaliza con un estado distinto de cero cuando aún queda trabajo pendiente:
lingo checkAñádelo como un paso de CI independiente antes de la compilación.
