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 krok za krokem provede lokalizací iOS aplikace: od nastavení CLI přes lokální překlad až po automatizaci pomocí GitHub App, takže se překlady nasazují při každém pushi.

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.

CLI rozpozná formát .xcstrings podle přípony souboru, zpracuje tuto JSON strukturu, přeloží každou položku přes lokalizační engine a zapíše překlady zpět do stejného souboru — se zachováním komentářů, pravidel množného čísla i metadat.

Předpoklady#

node -v

Nainstalujte a nastavte CLI#

Nainstalujte CLI, přihlaste se a pak nastavte projekt. Kompletní postup najdete v Quickstart.

npm install -g @lingo.dev/cli
lingo login

V kořenovém adresáři projektu spusťte lingo init a odpovězte na výzvy (zdrojový jazyk, cílové jazyky a vzor souborů odkazující na váš String Catalog), potom spusťte lingo link, aby se projekt propojil s vaší organizací a enginem. Tím se vytvoří .lingo/config.json:

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "MyApp/Localizable.xcstrings" }]
}

Commitněte .lingo/config.json — je to jediný zdroj pravdy pro to, co se má překládat. Formát .xcstrings se rozpoznává podle přípony souboru. Protože String Catalogs ukládají všechny jazyky v jednom souboru, není ve vzoru potřeba žádný zástupný symbol pro jazyk: CLI načte položky ve zdrojovém jazyce a zapíše všechny cílové jazyky zpět do stejného souboru. Kompletní schéma najdete v configuration reference.

{
  "files": [
    { "pattern": "MyApp/Localizable.xcstrings" },
    { "pattern": "MyAppWidgets/Localizable.xcstrings" }
  ]
}

Překládejte lokálně#

V kořenovém adresáři projektu spusťte první překlad:

lingo push --backfill-missing

CLI načte váš String Catalog, přeloží všechny chybějící položky přes váš lokalizační engine, počká na dokončení běhu a zapíše výsledky zpět do souboru .xcstrings. Otevřete soubor v Xcode a uvidíte doplněné překlady pro každý nakonfigurovaný jazyk.

Když upravíte zdrojové řetězce, běžné lingo push přeloží jen změny — položky, jejichž zdroj se nezměnil, se na serveru přeskočí a sledují se přes lockfile:

lingo push

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 to s GitHub App#

Nainstalujte si do repozitáře Lingo.dev GitHub App pro průběžnou lokalizaci — bez CI runneru, tajného API klíče i lockfile, o které byste se museli starat. Jakmile ji nainstalujete a nasměrujete na svůj .lingo/config.json (včetně engineId), začne automaticky reagovat na push i pull requesty: rozpozná změněné zdrojové řetězce, přeloží je přes váš engine a commitne aktualizovaný soubor .xcstrings zpět do větve nebo otevře pull request.

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

Použijte lingo check jako kontrolu před nasazením, abyste měli jistotu, že se do produkce nedostanou žádné nepřeložené řetězce. Nahlásí chybějící nebo zastaralé překlady a skončí s nenulovým stavovým kódem, pokud ještě zbývá práce:

lingo check

Přidejte ho jako samostatný CI krok před buildem.

Další kroky#