Localización de apps iOS con String Catalogs de Xcode

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 lleva paso a paso por todo el proceso de localización de una app iOS: configurar el CLI, traducir en local y automatizar con GitHub Actions para que las traducciones se publiquen con cada push.

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.

El tipo de bucket xcode-xcstrings del CLI interpreta esta estructura JSON, traduce cada entrada con el motor de localización y escribe las traducciones en el mismo archivo, conservando comentarios, reglas de plural y metadatos.

Requisitos previos#

node -v

Configura el CLI#

Crea un archivo i18n.json en la raíz del proyecto. El bucket xcode-xcstrings le indica al CLI que interprete el formato de String Catalog 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 String Catalogs almacenan todos los idiomas en un solo archivo, no hace falta ningún placeholder [locale] en el patrón include. El CLI lee las entradas del idioma de origen, las traduce y vuelve a escribir todos los idiomas de destino en el mismo archivo .xcstrings.

{
  "buckets": {
    "xcode-xcstrings": {
      "include": [
        "MyApp/Localizable.xcstrings",
        "MyAppWidgets/Localizable.xcstrings"
      ]
    }
  }
}

Traduce en local#

Configura tu API key y ejecuta el CLI:

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

El CLI lee tu String Catalog, identifica las entradas sin traducir mediante el lockfile, traduce el delta con tu motor de localización y escribe los resultados en el archivo .xcstrings. Abre el archivo en Xcode para ver las traducciones completadas para cada idioma configurado.

Para apuntar a un idioma específico durante el desarrollo:

npx lingo.dev@latest run --target-locale es

Notas 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 GitHub Actions#

Agrega un archivo de flujo de trabajo en .github/workflows/translate.yml para traducir con cada push:

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 API key como LINGODOTDEV_API_KEY en Settings > Secrets and variables > Actions dentro de tu repositorio de GitHub.

Verifica antes de desplegar#

Usa la bandera --frozen como puerta de control de despliegue para asegurarte de que no lleguen cadenas sin traducir a producción. El CLI finaliza con un estado distinto de cero si alguna entrada necesita traducción:

npx lingo.dev@latest run --frozen

Agrega esto como un paso de CI independiente antes de la compilación:

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

Siguientes pasos#