Lokalizace Android aplikace pomocí strings.xml

Lingo.dev CLI překládá Android string resources (strings.xml) přes nakonfigurovaný lokalizační engine. Typ bucketu android v CLI nativně rozumí prvkům <resources>, <string>, <string-array> a <plurals>, zachovává XML strukturu 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: nastavením CLI, lokálním překladem i automatizací přes GitHub Actions, aby se překlady nasazovaly s každým pushem.

Ukázkový repozitář

Naklonujte nebo forkněte lingodotdev/android-app-localization-example a postupujte podle návodu. Repozitář obsahuje funkční Android projekt se string resources, konfigurací CLI od Lingo.dev a GitHub Actions workflow.

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í.

text

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ů:

xml

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

Vytvořte lokalizační engine

Každé spuštění CLI posílá obsah přes lokalizační engine – tedy konfiguraci, která určuje použitý LLM model, glosář, hlas značky a instrukce. Vytvořte ho v Lingo.dev dashboardu a vygenerujte API klíč.

Ověřte verzi Node.js

CLI vyžaduje Node.js 18 nebo vyšší:

bash

node -v

Připravte Android projekt

Váš projekt potřebuje výchozí strings.xml v app/src/main/res/values/. Android Studio tento soubor vytvoří při založení nového projektu. Jak nastavit resource adresáře popisuje průvodce lokalizací pro Android.

Nastavení CLI#

V kořenovém adresáři projektu vytvořte soubor i18n.json. Bucket android říká CLI, aby parsovalo Android XML resources a vytvářelo samostatné soubory pro každý jazyk:

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

Placeholder [locale] se za běhu vyhodnotí na každý nakonfigurovaný kód jazyka. CLI dosadí zdrojový jazyk do vzoru – takže s source: "en" hledá values-en/strings.xml. Pro cílové jazyky pak vytvoří values-es/strings.xml, values-fr/strings.xml a další.

Propojení výchozího jazykového adresáře#

Android ukládá výchozí řetězce do values/ (bez přípony jazyka), ale CLI vyhodnocuje [locale] doslova a hledá values-en/strings.xml. Obě konvence propojíte vytvořením symlinku:

bash

cd app/src/main/res
ln -s values values-en

Díky tomu budou zdrojové řetězce dostupné jak v values/strings.xml (kde je očekává Android), tak v values-en/strings.xml (kde je hledá CLI). Symlink commitněte do repozitáře – git symlinky na macOS a Linuxu sleduje nativně.

Windows

Git ve Windows může podle konfigurace checkoutovat symlinky jako obyčejné textové soubory. Pokud používáte Windows, spusťte před klonováním git config core.symlinks true, nebo místo toho zkopírujte adresář values/ do values-en/.

Více resource souborů

Pokud váš projekt rozděluje řetězce do více souborů (například strings.xml a arrays.xml), uveďte je všechny. Symlink pokrývá celý adresář, takže všechny soubory uvnitř values/ jsou dostupné přes values-en/:

json

{
  "buckets": {
    "android": {
      "include": [
        "app/src/main/res/values-[locale]/strings.xml",
        "app/src/main/res/values-[locale]/arrays.xml"
      ]
    }
  }
}

Překlad lokálně#

Nastavte API klíč a spusťte CLI:

bash

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

CLI načte zdrojový strings.xml, pomocí lockfile identifikuje nepřeložené položky, přeloží rozdíl přes váš lokalizační engine a zapíše výsledky do cílových adresářů values-[locale]/. Přeložené řetězce si můžete ověřit otevřením libovolného cílového souboru.

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

bash

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

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:

xml

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

json

{
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"],
      "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 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:

Překlady se commitují přímo do main – bez zbytečného tření, ideální pro menší týmy:

yaml

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 svém GitHub repozitáři.

Kontrola před nasazením#

Pomocí příznaku --frozen vytvoříte nasazovací bránu, která zajistí, že se do produkce nedostanou žádné nepřeložené řetězce. Pokud některé položky potřebují překlad, CLI skončí s nenulovým stavem:

bash

npx lingo.dev@latest run --frozen

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

yaml

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

Další kroky#

Lokalizace mobilních aplikací

Přehled všech mobilních platforem – iOS, Android, Flutter, React Native

CI/CD Workflows

Osvědčené postupy pro GitHub Actions, GitLab CI a Bitbucket Pipelines

Glosáře

Uzamkněte názvy značek a technické termíny, aby se nepřekládaly

Zamykání klíčů

Zkopírujte konkrétní hodnoty bez překladu

Ukázkový repozitář

Jak funguje lokalizace v Androidu#

text

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ů:

xml

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

Vytvořte lokalizační engine

Ověřte verzi Node.js

CLI vyžaduje Node.js 18 nebo vyšší:

bash

node -v

Připravte Android projekt

Nastavení CLI#

V kořenovém adresáři projektu vytvořte soubor i18n.json. Bucket android říká CLI, aby parsovalo Android XML resources a vytvářelo samostatné soubory pro každý jazyk:

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"]
    }
  }
}

Propojení výchozího jazykového adresáře#

Android ukládá výchozí řetězce do values/ (bez přípony jazyka), ale CLI vyhodnocuje [locale] doslova a hledá values-en/strings.xml. Obě konvence propojíte vytvořením symlinku:

bash

cd app/src/main/res
ln -s values values-en

Windows

Více resource souborů

json

{
  "buckets": {
    "android": {
      "include": [
        "app/src/main/res/values-[locale]/strings.xml",
        "app/src/main/res/values-[locale]/arrays.xml"
      ]
    }
  }
}

Překlad lokálně#

Nastavte API klíč a spusťte CLI:

bash

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

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

bash

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

Množné číslo#

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:

xml

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

Zamykání klíčů#

json

{
  "buckets": {
    "android": {
      "include": ["app/src/main/res/values-[locale]/strings.xml"],
      "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 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:

Překlady se commitují přímo do main – bez zbytečného tření, ideální pro menší týmy:

yaml

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 svém GitHub repozitáři.

Kontrola před nasazením#

bash

npx lingo.dev@latest run --frozen

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

yaml

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

Další kroky#

Lokalizace mobilních aplikací

Přehled všech mobilních platforem – iOS, Android, Flutter, React Native

CI/CD Workflows

Osvědčené postupy pro GitHub Actions, GitLab CI a Bitbucket Pipelines

Glosáře

Uzamkněte názvy značek a technické termíny, aby se nepřekládaly

Zamykání klíčů

Zkopírujte konkrétní hodnoty bez překladu