GitHub App

GitHub App od Lingo.dev nastaví pro repozitář průběžnou lokalizaci pomocí .lingo/config.json.

Požadavky#

Před instalací aplikace se ujistěte, že máte:

• Organizaci Lingo.dev s aktivní funkcí integrace s GitHubem
• lokalizační engine v této organizaci
• Administrátorský přístup k organizaci nebo repozitáři na GitHubu, které chcete připojit

Nainstalujte aplikaci GitHub#

1. V Lingo.dev otevřete svou organizaci.
2. Přejděte do Studio > All integrations.
3. Na kartě GitHub klikněte na Install on GitHub.
4. Na GitHubu vyberte účet nebo organizaci, do kterých chcete aplikaci nainstalovat.
5. Vyberte buď All repositories, nebo Only select repositories.
6. Klikněte na Install.

GitHub vás vrátí do Lingo.dev na obrazovku Připojit GitHub:

1. Vyberte organizaci v Lingo.dev, přes kterou tento účet GitHub lokalizuje. Automaticky se vybere organizace, kterou jste naposledy otevřeli.
2. Klikněte na Připojit.
3. Jakmile se zobrazí GitHub připojen, klikněte na Zobrazit integraci a otevřete připojení.

Připojení se zobrazí v postranním panelu Studia v části Připojeno. Na kartě Nastavení uvidíte Účet, Typ účtu, Instalaci, Repozitáře a také to, jestli Připojení funguje. Na kartě Spuštění workflow najdete všechna spuštění aplikace včetně repozitáře a informace, jestli je spustil push nebo pull request.

Pokud budete chtít později přidat nebo odebrat repozitáře, otevřete kartu Nastavení připojení a použijte možnost Spravovat na GitHubu: přístup k repozitářům se vždy nastavuje na GitHubu přímo u instalace.

Pokud jste místo instalace o instalaci jen požádali, Lingo.dev zobrazí O instalaci bylo požádáno: správce organizace na GitHubu ji musí schválit. Jakmile to udělá, GitHub vás vrátí na obrazovku Připojit GitHub, kde dokončíte nastavení. Správce si může žádost zkontrolovat na GitHubu v části organizace Nastavení > GitHub Apps. GitHub také zobrazuje čekající žádosti o aplikace vlastníkům organizace v nastavení organizace.

Přidání konfigurace repozitáře#

V repozitáři, do kterého jste aplikaci nainstalovali, vytvořte soubor .lingo/config.json:

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "docs/en/**/*.mdx" },
    { "pattern": "locales/en.json" }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": true }
    },
    "safety": {
      "requireApproval": false
    }
  }
}

Zapište konfiguraci repozitáře pomocí CLI. Následující příkazy spusťte v uvedeném pořadí:

1. Spusťte npx @lingo.dev/cli init a zapište zdrojový jazyk, cílové jazyky a vzory pro výběr souborů do .lingo/config.json.
2. Spusťte npx @lingo.dev/cli login, přihlaste se a uložte své přihlašovací údaje lokálně do ~/.lingo/credentials.json.
3. Spusťte npx @lingo.dev/cli link a vyberte organizaci a engine. Tím se do .lingo/config.json přidají orgId a engineId.

Příkaz init nezapisuje sekci github. Pokud ji potřebujete, zkopírujte ji z příkladu výše. Podrobnosti najdete v průvodci rychlým startem s CLI.

Vzory souborů#

Vzory files odkazují na zdrojové soubory (ve výchozím jazyce). Aplikace porovnává změněné soubory s těmito vzory a zpracuje jen podporované zdrojové soubory, které odpovídají.

Vzory jsou relativní vůči repozitáři, rozlišují velikost písmen a mohou používat:

• * pro shodu v rámci jednoho segmentu cesty
• **/ pro shodu v libovolné hloubce adresářů

Vzory nemohou začínat na / a nemohou obsahovat ...

{
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "src/content/en/**/*.mdx" },
    { "pattern": "messages/en.jsonc" }
  ]
}

Možnosti souborů#

Každá položka v files může kromě svého pattern obsahovat i další možnosti. Všechny jsou nepovinné a každá se vztahuje jen na určité formáty.

Položky translateComponentProps jsou buď názvem propu, který platí pro daný prop u libovolné komponenty nebo tagu, nebo objektem, který omezuje props na pojmenované komponenty nebo tagy:

{
  "files": [
    {
      "pattern": "src/content/en/**/*.mdx",
      "translateFrontmatterFields": ["title", "description"],
      "translateComponentProps": [
        "alt",
        { "component": ["Callout", "Hero"], "props": ["title", "subtitle"] }
      ]
    },
    {
      "pattern": "locales/en.json",
      "lockedKeys": ["app.version"],
      "injectLocale": { "enabled": true, "key": "language" }
    }
  ]
}

Kam se zapisují lokalizované soubory#

Aplikace odvodí každou cílovou cestu ze zdrojové cesty a kódů jazyků ve vaší konfiguraci:

Jako kód jazyka použijte celý název adresáře nebo souboru. Pokud například zdrojové soubory leží v docs/en-US/, nastavte "sourceLocale": "en-US", ne "en". Pokud zdrojové řetězce leží v messages/en.json, nastavte "sourceLocale": "en".

Když zdrojová cesta obsahuje adresář s názvem jazyka, aplikace tento adresář nahradí. Když je zdrojová cesta souborem pojmenovaným podle jazyka, aplikace nahradí název souboru. Pokud neexistuje ani jeden z těchto vzorů, aplikace umístí přeložený soubor do nového adresáře cílového jazyka vedle zdrojového souboru.

Katalogy řetězců jsou výjimkou. Protože jeden soubor .xcstrings obsahuje všechny jazyky, cílová cesta je stejná jako zdrojová — aplikace zapisuje každý jazyk do téhož souboru a nikdy nepřidává adresář ani název souboru pro jazyk.

Workflow#

Push do výchozí větve#

Když je ve výchozí větvi přidán nebo změněn odpovídající zdrojový soubor, aplikace ho přeloží a commitne lokalizované soubory do:

lingo/translations/<default-branch>

Poté otevře nebo aktualizuje pull request z této překladové větve zpět do výchozí větve. Pokud překladová větev už existuje, přidá do ní nové commity.

Pokud je ve stejném pushi přidán nebo změněn cílový soubor, aplikace ho považuje za už zpracovaný a zahrne ho do překladového PR místo toho, aby ho přepsala.

Pull requesty#

Když má github.workflows.onPullRequest.enabled hodnotu true, aplikace zkontroluje změny v pull requestu a vyhledá odpovídající zdrojové soubory. Přeložené soubory commitne přímo do PR větve.

Aplikace nezapisuje do PR větví z forků a z komentáře v PR nezapisuje do výchozí větve. Aby aplikace mohla commitnout překlady, musí být pull request otevřený.

U PR Lingo.dev aktualizuje komentář s přeloženými soubory a případnými chybami.

Přírůstkové aktualizace a obnova#

U existujících cílových souborů aplikace překládá jen změny ve zdroji, které dokáže rozpoznat, místo aby znovu generovala celý soubor. U nových cílových souborů vytvoří lokalizovaný soubor pro každý nakonfigurovaný cílový jazyk.

Pokud předchozí lokalizace PR vynechala změnu ve zdroji nebo selhala před aktualizací cílového souboru, může se při další synchronizaci PR stav obnovit porovnáním zdroje v PR se zdrojem v základní větvi a překladem chybějící změny.

Pokud zdrojový soubor v commitu, který se právě zpracovává, už neexistuje, aplikace ho přeskočí.

Režim schvalování#

Pokud chcete před spuštěním automatických překladů krok lidského schválení, nastavte github.safety.requireApproval na true.

Při pushech do výchozí větve zobrazuje check run Lingo.dev akce Approve a Deny. U pull requestů aplikace přidá komentář s návrhem překladu; odpovězte:

/lingo approve

Příkazy /lingo translate s omezeným rozsahem toto schvalování nevyžadují.

Ruční PR příkaz#

Pomocí /lingo v komentáři k pull requestu můžete přeložit změny ve zdrojových souborech, doplnit chybějící cílové soubory nebo znovu přeložit vybrané klíče.

Přeložte změny ve zdrojových souborech v pull requestu a zachovejte překlady nezměněného obsahu:

/lingo translate

Chcete-li doplnit chybějící cílové soubory, zadejte globové vzory souborů:

/lingo translate docs/en/**/*.md

/lingo translate docs/en/**/*.mdx --locales fr,es

/lingo translate docs/en/**/*.md --force

Přehled příkazů:

Příkaz musí být na samostatném řádku. Globy se porovnávají se soubory, které zároveň odpovídají vašim nakonfigurovaným zdrojovým vzorům files. Stejně jako konfigurační vzory nesmějí globy příkazů začínat na / a nesmějí obsahovat ...

Pokud zadáte globové vzory souborů a vynecháte --key, spustí se /lingo translate <glob>... v režimu doplňování: vytvoří pouze cílové soubory, které ve větvi PR chybí. Pokud chcete odpovídající cílové soubory, které již existují, vygenerovat znovu, přidejte --force.

Znovu přeložte vybrané klíče#

Pomocí --key aktualizujte vybrané pojmenované klíče a zachovejte ostatní překlady včetně přijatých úprav jiných klíčů:

/lingo translate locales/en.json --key "auth.login" --locales fr,es

Vzory klíčů podporují přesné shody, předpony i globové vzory:

Chcete-li vybrat více vzorů, zopakujte --key. Vzory klíčů obsahující mezery uzavřete do uvozovek. Globové vzory souborů a --locales zužují rozsah požadavku; pokud globové vzory souborů vynecháte, vyberou se všechny nakonfigurované zdrojové soubory:

/lingo translate --key "auth.*" --key "checkout.submit" --locales fr

Překlad omezený na vybrané klíče vyžaduje formát s pojmenovanými klíči a existující překlad pro každý vybraný cílový jazyk. Formáty bez pojmenovaných klíčů a jazyky bez existujících překladů se přeskočí. Chcete-li nejprve vytvořit chybějící cílové soubory, spusťte /lingo translate <glob>... bez --key. Přidáním --force k příkazu omezenému na vybrané klíče se výběr klíčů nerozšíří ani se nenahradí ostatní překlady.

Přidejte vlastní kontext pro konkrétní spuštění#

Přidejte --context a vysvětlete význam vybraného klíče nebo upřesněte tón a používání velkých a malých písmen:

/lingo translate --key "keyname" --context "button label, keep sentence case"

--context vyžaduje --key. Kontext zadejte jednou; platí pro všechny vybrané klíče a jazyky v daném spuštění. Uchovává se spolu se spuštěním pro opakované pokusy a historii, ale nemění uložená pravidla ani instrukce engine a nepřenáší se do dalších spuštění. Stávající pravidla pro glosář, zástupné symboly a výstupní formát platí i nadále.

Příkaz zapište na jeden řádek. Kontext obsahující mezery uzavřete do jednoduchých nebo dvojitých uvozovek; použít můžete i --context="button label". Chcete-li do textu vložit stejnou uvozovku, která jej ohraničuje, vložte před ni zpětné lomítko:

/lingo translate --key "checkout.submit" --context "Use \"Save\" as a button label"

V kontextu uzavřeném do uvozovek se dekóduje pouze \\ a zpětné lomítko před uvozovkou, která text ohraničuje. Zástupné symboly jako $name a ${name}, sekvence jako \n i interpunkce zůstávají v doslovné podobě.

Podporované formáty#

GitHub App rozpozná tyto formáty podle přípony souboru:

• JSON (.json)
• JSONC (.jsonc)
• Markdown (.md)
• MDX (.mdx)
• Markdoc
• Katalog řetězců Xcode (.xcstrings)

Podporované jsou také dokumenty OpenAPI zapsané v YAML, ale nerozpoznají se automaticky. U vzoru souboru nastavte "format": "yaml-openapi":

{
  "files": [
    { "pattern": "openapi/en.yaml", "format": "yaml-openapi" }
  ]
}

Katalogy řetězců Xcode#

Katalog řetězců Xcode uchovává všechny jazyky v jednom souboru .xcstrings, takže ho aplikace překládá přímo v něm, místo aby vytvářela samostatný soubor pro každý jazyk. Cílová cesta je stejná jako zdrojová: každý cílový jazyk se zapisuje do stejného souboru vedle zdrojového jazyka a všech jazyků, které už byly přeloženy. Nasměrujte zdrojový vzor přímo na katalog a nastavte sourceLocale na jeho vývojový jazyk:

{
  "sourceLocale": "en",
  "targetLocales": ["es-MX", "fr-CA", "pt-BR"],
  "files": [{ "pattern": "**/*.xcstrings" }]
}

Velké aktualizace#

Aplikace může výstup překladu rozdělit do více commitů. To se stane, když by jedno spuštění zapsalo víc než 100 souborů v jednom commitu nebo víc než 5 MB přeloženého obsahu souborů v jednom commitu.

Když k tomu dojde, zprávy commitů obsahují číslo dávky, například:

feat: Lingo.dev translations (1/3)
feat: Lingo.dev translations (2/3)
feat: Lingo.dev translations (3/3)

Co se stane, když nic neodpovídá#

Pokud chybí .lingo/config.json, aplikace repozitář tiše přeskočí. Jakmile konfigurace existuje, neplatná konfigurace vytvoří neúspěšný check run a u PR také komentář s chybou validace.

Pokud žádné změněné soubory neodpovídají vašim zdrojovým vzorům, aplikace se dokončí bez zapsání překladů. U /lingo translate bot odpoví stručným vysvětlením, například že neodpovídají žádné soubory, žádné jazyky nebo že všechny cílové soubory už existují.

Při odeslání změn, kterým přidáte .lingo/config.json, se přeloží pouze zdrojové soubory odpovídající nastaveným vzorům, které se při tomto odeslání změnily. U stávajících zdrojových souborů, které zůstaly beze změny, je třeba překlady doplnit samostatně. Chcete-li pro ně vytvořit chybějící cílové soubory, otevřete žádost o začlenění změn z větve ve stejném repozitáři, nikoli z forku. Do komentáře k této žádosti napište /lingo translate <glob>.

Další kroky#