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 paso a paso en la localización completa de una app iOS: configurar la CLI, traducir en local y automatizarlo con GitHub Actions para que las traducciones se publiquen con cada push.
Repositorio de demostración
Clona o haz un fork de lingodotdev/ios-app-localization-example para seguir el tutorial. El repositorio incluye un proyecto de Xcode funcional con catálogos de cadenas, una configuración de la CLI de Lingo.dev y un flujo de trabajo de GitHub Actions.
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 |
El tipo de bucket xcode-xcstrings de la CLI 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 plural y metadatos.
Requisitos previos#
Crea un motor de localización
Cada ejecución de la CLI envía el contenido a través de un motor de localización: la configuración que determina qué modelo de LLM, glosario, voz de marca e instrucciones se aplican. Crea uno en el panel de Lingo.dev y genera una clave de API.
Comprueba Node.js
La CLI requiere Node.js 18 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.
Configura la CLI#
Crea un archivo i18n.json en la raíz del proyecto. El bucket xcode-xcstrings indica a la CLI que analice el formato de catálogo de cadenas y modifique el archivo directamente:
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"xcode-xcstrings": {
"include": ["MyApp/Localizable.xcstrings"]
}
}
}Como los catálogos de cadenas almacenan todos los idiomas en un único archivo, no hace falta ningún marcador de posición [locale] en el patrón include. La CLI lee las entradas del idioma de origen, las traduce y vuelve a escribir todos los idiomas de destino en el mismo archivo .xcstrings.
Varios catálogos de cadenas
Si tu proyecto utiliza varios archivos de catálogo de cadenas (por ejemplo, uno por cada target de framework), inclúyelos todos en el array include:
{
"buckets": {
"xcode-xcstrings": {
"include": [
"MyApp/Localizable.xcstrings",
"MyAppWidgets/Localizable.xcstrings"
]
}
}
}Traduce en local#
Configura tu clave de API y ejecuta la CLI:
export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest runLa CLI lee tu catálogo de cadenas, identifica las entradas sin traducir mediante el lockfile, traduce el delta a través de tu motor de localización y vuelve a escribir los resultados en el archivo .xcstrings. Abre el archivo en Xcode para ver las traducciones rellenadas para cada idioma configurado.
Para trabajar con un idioma concreto durante el desarrollo:
npx lingo.dev@latest run --target-locale esNotas 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.
Automatízalo con GitHub Actions#
Añade un archivo de flujo de trabajo en .github/workflows/translate.yml para traducir con cada push:
Las traducciones se confirman directamente en main: cero fricción, ideal para equipos pequeños:
name: Translate
on:
push:
branches: [main]
permissions:
contents: write
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lingo.dev
uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}Guarda tu clave de API como LINGODOTDEV_API_KEY en Settings > Secrets and variables > Actions de tu repositorio de GitHub.
Verifica antes de desplegar#
Usa la marca --frozen como control previo al despliegue para asegurarte de que ninguna cadena sin traducir llegue a producción. La CLI finaliza con un estado distinto de cero si alguna entrada necesita traducción:
npx lingo.dev@latest run --frozenAñádelo como un paso de CI independiente antes de la compilación:
- name: Verify translations
run: npx lingo.dev@latest run --frozen