El CLI de Lingo.dev traduce los String Catalogs de Xcode (.xcstrings) mediante un motor de localización configurado. Los String Catalogs son el formato moderno de localización de Apple, introducido en Xcode 15, que reúne todos los idiomas en un solo archivo JSON. El CLI modifica ese archivo directamente, sin necesidad de directorios por idioma.
Esta guía te acompaña de principio a fin en la localización de una app de iOS: configurar la CLI, traducir de forma local y automatizar con la GitHub App para que las traducciones se publiquen en cada push.
Repositorio de ejemplo
Clona o haz un fork de lingodotdev/ios-app-localization-example para seguir el paso a paso. El repositorio incluye un proyecto de Xcode funcional con String Catalogs y una configuración de la CLI de Lingo.dev.
Cómo funcionan los String Catalogs#
Antes de Xcode 15, la localización en iOS requería gestionar archivos separados .strings y .stringsdict en distintos directorios [locale].lproj/. Los String Catalogs reemplazan ese enfoque con 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 agrega una entrada al String Catalog. Cada entrada registra la cadena de origen, sus traducciones para cada idioma configurado y un campo opcional de comentario que aporta contexto a quienes traducen.
| Aspecto | .strings heredado | String Catalogs .xcstrings |
|---|---|---|
| Cantidad de archivos | Uno por idioma y por tabla | Un solo archivo, todos los idiomas |
| Formato | Texto clave-valor | JSON estructurado |
| Soporte para plurales | Archivo .stringsdict separado | Reglas de plural integradas |
| Integración con Xcode | Exportación/importación manual | Detección automática |
| Notas para traductores | No disponible | Campo de comentario por entrada |
La CLI detecta el formato .xcstrings a partir de la extensión del archivo, analiza esta estructura JSON, traduce cada entrada a través del motor de localización y vuelve a escribir las traducciones en el mismo archivo, conservando comentarios, reglas de pluralización y metadatos.
Requisitos previos#
Crea un motor de localización
Cada traducción envía el contenido a través de un motor de localización, la configuración que define qué modelo de LLM, glossary, voz de marca y reglas se aplican. Crea uno en el panel de Lingo.dev y genera una API key.
Verifica 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 agrega tus idiomas de destino. Xcode crea las entradas del String Catalog para cada idioma que agregues. Consulta la documentación sobre localización de Apple para más detalles.
Instala y configura la CLI#
Instala la CLI, autentícate y luego configura el proyecto. Consulta el Quickstart para ver el recorrido completo.
npm install -g @lingo.dev/cli
lingo loginEjecuta lingo init en la raíz de tu proyecto y responde las indicaciones (idioma de origen, idiomas de destino y el patrón de archivos que apunta a tu String Catalog); luego ejecuta lingo link para vincular el proyecto con tu organización y motor. En conjunto, estos comandos generan 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 solo 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 en ese mismo archivo. Consulta la Referencia de configuración para ver el esquema completo.
Varios String Catalogs
Si tu proyecto usa varios archivos de String Catalog (por ejemplo, uno por target de framework), agrega una entrada files para cada uno:
{
"files": [
{ "pattern": "MyApp/Localizable.xcstrings" },
{ "pattern": "MyAppWidgets/Localizable.xcstrings" }
]
}Traduce en local#
Desde la raíz de tu proyecto, ejecuta la primera traducción:
lingo push --backfill-missingLa CLI lee tu String Catalog, traduce cada entrada faltante a través de tu motor de localización, espera a que la ejecución termine y escribe los resultados de nuevo en el archivo .xcstrings. Abre el archivo en Xcode para ver las traducciones completadas para 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 cambió se omiten del lado del servidor y se rastrean mediante el lockfile:
lingo pushNotas para traductores#
Los String Catalogs admiten un campo de comentario por entrada que el 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 de String Catalog y agrega un comentario en el panel Inspector. El comentario se guarda en el JSON .xcstrings:
{
"sourceLanguage": "en",
"strings": {
"Set": {
"comment": "Refers to a collection of items, not the verb",
"localizations": { }
}
}
}El CLI envía ese comentario junto con la cadena, guiando al modelo hacia la interpretación correcta. "Set", sin contexto, podría traducirse como verbo en muchos idiomas; el comentario elimina esa ambigüedad. Consulta Translator Notes para ver más patrones.
Plurales#
Los String Catalogs manejan las formas plurales de forma nativa con las reglas de plural de CLDR. Cuando defines una variación plural en Xcode, el String Catalog guarda reglas para cada categoría plural (zero, one, two, few, many, other) que requiere el idioma de destino.
El 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 resuelve estas diferencias automáticamente.
Automatiza con la GitHub App#
Instala la GitHub App de Lingo.dev en tu repositorio para Localización continua, sin runners de CI, secretos de API key ni lockfiles que administrar. Una vez instalada y apuntando a tu .lingo/config.json (con su engineId), reacciona automáticamente a los pushes y pull requests: detecta las cadenas de origen modificadas, las traduce a través de tu motor y hace commit del .xcstrings actualizado en la rama o abre un pull request.
¿Prefieres ejecutarlo por tu cuenta?
También puedes ejecutar lingo push desde tu propio job de CI (cualquier runner con Node.js) y hacer commit de los resultados, autenticándote con LINGO_API_KEY. Consulta CI/CD Workflows para ver los patrones basados en runner.
Verifica antes de desplegar#
Usa lingo check como puerta de despliegue para asegurarte de que no se publiquen cadenas sin traducir en producción. Informa sobre traducciones faltantes o desactualizadas y finaliza con un estado distinto de cero cuando aún queda trabajo por hacer:
lingo checkAgrégalo como un paso de CI independiente antes de tu compilación.
