Lokalizace Android aplikace pomocí strings.xml

Lingo.dev CLI překládá androidové string resources (strings.xml) přes nakonfigurovaný lokalizační engine. Ve formátu android CLI nativně rozumí prvkům <resources>, <string>, <string-array> a <plurals>, zachovává strukturu XML a generuje správné kategorie množného čísla pro každý cílový jazyk.

Tento návod vás provede lokalizací Android aplikace od začátku do konce: od konfigurace CLI přes lokální překlad až po automatizaci v CI, aby se překlady nasazovaly s každým pushem.

Jak funguje lokalizace v Androidu#

Android používá konvenci resource adresářů, ve které má každý jazyk vlastní adresář values-[locale]/. Systém pak za běhu načte správný strings.xml podle nastavení jazyka zařízení.

app/src/main/res/
  values/              # Default (source) strings
    strings.xml
  values-es/           # Spanish
    strings.xml
  values-fr/           # French
    strings.xml
  values-ja/           # Japanese
    strings.xml

Typický strings.xml obsahuje tři typy prvků:

<resources>
  <!-- Simple strings -->
  <string name="app_name">My App</string>
  <string name="welcome_message">Welcome back!</string>

  <!-- String arrays -->
  <string-array name="planets">
    <item>Mercury</item>
    <item>Venus</item>
    <item>Earth</item>
  </string-array>

  <!-- Plurals -->
  <plurals name="items_count">
    <item quantity="one">%d item</item>
    <item quantity="other">%d items</item>
  </plurals>
</resources>

CLI zpracuje všechny tři typy prvků, přeloží jejich obsah přes lokalizační engine a zapíše soubory pro jednotlivé jazyky do správných adresářů values-[locale]/.

Co budete potřebovat#

node -v

npm install -g @lingo.dev/cli

lingo login

Nastavení CLI#

V kořenovém adresáři projektu spusťte lingo init. Tím vytvoříte .lingo/config.json se zdrojovým a cílovými jazyky i vzory souborů, pak spusťte lingo link a připojte organizaci a engine. Výsledek bude vypadat takto:

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android"
    }
  ]
}

Pattern míří na váš výchozí adresář resources – nekvalifikovaný values/, tedy přesně tam, kde Android očekává zdrojové řetězce. Neobsahuje žádný kód jazyka a ani ho nepotřebuje.

{
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android"
    },
    {
      "pattern": "app/src/main/res/values/arrays.xml",
      "format": "android"
    }
  ]
}

Commitněte .lingo/config.json do repozitáře.

Adresáře jazyků a kvalifikátory#

Android ukládá výchozí jazyk do nekvalifikovaného adresáře values/, takže zdrojová cesta neobsahuje žádný kód jazyka. CLI to rozpozná: bere samotné values/ jako zdrojový jazyk a ke každému dalšímu jazyku přidá cílový kvalifikátor.

Regionální varianty a jazyky se skriptem je tady dobré pochopit, protože resource qualifier není prostě jen syrový tag BCP 47. Android podporuje dva zápisy: starší formát jazyk-oblast (values-pt-rBR/) a formát BCP 47 s prefixem b+ (values-b+pt+BR/, od API 24 výš). Adresář pojmenovaný values-pt-BR/ Android zcela ignoruje – řetězce v něm sice budou existovat, ale nikdy se nenačtou.

Když nastavíte "format": "android", CLI za vás vygeneruje správný zápis: starší formát všude, kde jím lze jazyk vyjádřit, a b+ pro skripty, třípísmenné jazyky a číselné regiony.

Překlad lokálně#

Spusťte CLI. Při prvním spuštění — nebo kdykoli přidáte nový cílový jazyk — použijte --backfill-missing, aby se přeložily všechny existující řetězce:

lingo push --backfill-missing

CLI načte váš zdrojový soubor strings.xml, pomocí run state identifikuje nepřeložené položky, přeloží změny přes váš lokalizační engine a zapíše výsledky do cílových adresářů values-[locale]/. Otevřete libovolný cílový soubor a uvidíte přeložené řetězce.

Při dalších spuštěních lingo push překládá jen to, co se změnilo:

lingo push

Pokud chcete běh omezit na konkrétní soubory, předejte glob. Patterny se porovnávají se zdrojovými cestami, takže rozsah určujte podle zdrojového souboru, ne cílového:

lingo push "app/src/main/res/values/strings.xml"

Chcete-li do svého pracovního stromu stáhnout překlady vytvořené jinde (například v CI), spusťte lingo pull.

Množné číslo#

Android používá prvky <plurals> s CLDR quantity strings (zero, one, two, few, many, other) pro práci s tvary množného čísla. Různé jazyky vyžadují různé kategorie množného čísla – angličtina potřebuje dvě (one a other), ruština čtyři a arabština šest.

CLI při překladu zachovává strukturu <plurals> a generuje správné quantity položky pro každý cílový jazyk. Zdrojová položka se dvěma kategoriemi:

<plurals name="messages_count">
  <item quantity="one">%d new message</item>
  <item quantity="other">%d new messages</item>
</plurals>

Výsledkem jsou správné kategorie pro každý cílový jazyk. Lokalizační engine ví, která CLDR pravidla množného čísla platí pro jednotlivé jazyky, a generuje jen ty kategorie, které daný jazyk skutečně vyžaduje.

Zamykání klíčů#

Některé hodnoty řetězců by měly zůstat ve všech jazycích stejné – například názvy značek, API endpointy nebo formátovací vzory. Pomocí zamykání klíčů tyto hodnoty zkopírujete bez překladu:

{
  "files": [
    {
      "pattern": "app/src/main/res/values/strings.xml",
      "format": "android",
      "lockedKeys": ["app_name", "api_base_url"]
    }
  ]
}

Uzamčené klíče se zkopírují ze zdroje do všech cílových souborů, aniž by vstoupily do překladové pipeline.

Automatizace v CI#

Doporučený způsob, jak udržovat překlady aktuální, je Lingo.dev GitHub App. Běží na serveru, čte vaše commitnuté .lingo/config.json a engineId a automaticky otevírá aktualizace překladů — bez runneru, bez uložených secretů a bez správy lockfile z vaší strany. Nainstalujte ji a propojte ji se svým repozitářem, aby překládala při každém pushi.

Pokud chcete CLI spouštět ve vlastní pipeline, přidejte workflow, které CLI nainstaluje a spustí lingo push:

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push --backfill-missing
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}

Uložte svůj API key jako LINGO_API_KEY v Settings > Secrets and variables > Actions ve svém GitHub repozitáři a pak v navazujícím kroku commitněte aktualizované cílové soubory (nebo otevřete pull request).

Kontrola před nasazením#

Použijte lingo check jako podmínku nasazení, abyste měli jistotu, že se do produkce nedostanou žádné nepřeložené řetězce. Příkaz skončí s nenulovým stavovým kódem, pokud některé položky vyžadují překlad:

lingo check

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

- name: Verify translations
  run: lingo check
  env:
    LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}

Další kroky#