Lokalizace iOS aplikace pomocí Xcode String Catalogs

Lingo.dev CLI překládá Xcode String Catalogs (.xcstrings) pomocí nakonfigurovaného lokalizačního engine. String Catalogs jsou moderní lokalizační formát od Applu, představený v Xcode 15, který ukládá všechny jazyky do jednoho JSON souboru. CLI tento soubor upravuje přímo na místě – bez potřeby samostatných adresářů pro jednotlivé jazyky.

Tento průvodce vás provede lokalizací iOS aplikace od začátku do konce: od konfigurace CLI přes lokální překlad až po automatizaci s GitHub Actions, aby se překlady nasazovaly s každým pushem.

Jak fungují String Catalogs#

Před Xcode 15 znamenala lokalizace iOS správu samostatných souborů .strings a .stringsdict v různých adresářích [locale].lproj/. String Catalogs to nahrazují jediným souborem Localizable.xcstrings, který Xcode spravuje automaticky.

Když ve SwiftUI nebo UIKit označíte řetězec jako lokalizovatelný, Xcode ho při buildu rozpozná a přidá položku do String Catalogu. Každá položka sleduje zdrojový řetězec, jeho překlady pro každý nakonfigurovaný jazyk a nepovinné pole s komentářem, které překladatelům poskytuje kontext.

Typ bucketu xcode-xcstrings v CLI parsuje tuto JSON strukturu, překládá každou položku přes lokalizační engine a zapisuje překlady zpět do stejného souboru – se zachováním komentářů, pravidel pro plurály i metadat.

Předpoklady#

node -v

Nakonfigurujte CLI#

V kořenovém adresáři projektu vytvořte soubor i18n.json. Bucket xcode-xcstrings řekne CLI, aby parsovalo formát String Catalog a upravovalo soubor přímo na místě:

{
  "$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"]
    }
  }
}

Protože String Catalogs ukládají všechny jazyky do jediného souboru, v include patternu není potřeba placeholder [locale]. CLI načte položky zdrojového jazyka, přeloží je a zapíše všechny cílové jazyky zpět do stejného souboru .xcstrings.

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

Překládejte lokálně#

Nastavte API klíč a spusťte CLI:

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

CLI načte váš String Catalog, pomocí lockfile identifikuje nepřeložené položky, přeloží delta změny přes váš lokalizační engine a zapíše výsledky zpět do souboru .xcstrings. Otevřete soubor v Xcode a uvidíte vyplněné překlady pro každý nakonfigurovaný jazyk.

Pokud chcete při vývoji cílit na konkrétní jazyk:

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

Poznámky pro překladatele#

String Catalogs podporují u každé položky pole s komentářem, které CLI zahrnuje do požadavků na překlad. Tyto komentáře dávají lokalizačnímu engine kontext – pomáhají rozlišit význam termínů, upřesnit tón nebo popsat, kde se řetězec v UI zobrazuje.

V Xcode vyberte v editoru String Catalog řetězec a přidejte komentář v panelu inspektoru. Komentář se uloží do JSON .xcstrings:

{
  "sourceLanguage": "en",
  "strings": {
    "Set": {
      "comment": "Refers to a collection of items, not the verb",
      "localizations": { }
    }
  }
}

CLI tento komentář odesílá spolu s řetězcem a vede model ke správné interpretaci. „Set“ se bez kontextu může v mnoha jazycích přeložit jako sloveso – komentář tuto nejednoznačnost odstraňuje. Další vzory najdete v Translator Notes.

Plurály#

String Catalogs nativně pracují s tvary množného čísla pomocí CLDR pravidel pro plurály. Když v Xcode definujete variantu množného čísla, String Catalog uloží pravidla pro každou kategorii plurálu (zero, one, two, few, many, other), kterou cílový jazyk vyžaduje.

CLI tuto strukturu při překladu zachovává a generuje správné kategorie plurálu pro každý cílový jazyk. Angličtina používá dvě kategorie (one a other), ale arabština jich potřebuje šest, polština čtyři a japonština jednu. Lokalizační engine tyto rozdíly řeší automaticky.

Automatizujte s GitHub Actions#

Přidejte workflow soubor do .github/workflows/translate.yml, aby se překlady spouštěly při každém pushi:

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 }}

Uložte API klíč jako LINGODOTDEV_API_KEY v Settings > Secrets and variables > Actions ve vašem GitHub repozitáři.

Ověření před nasazením#

Použijte příznak --frozen jako pojistku před nasazením, abyste měli jistotu, že se do produkce nedostanou žádné nepřeložené řetězce. Pokud některé položky stále vyžadují překlad, CLI skončí s nenulovým stavovým kódem:

npx lingo.dev@latest run --frozen

Přidejte to jako samostatný CI krok před buildem:

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

Další kroky#