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

Připojení GitHub App#

1. V Lingo.dev otevřete svou organizaci.
2. Přejděte do Settings.
3. V sekci integrací najděte GitHub (App).
4. Na řádku GitHub (App) klikněte na Connect.
5. Na GitHubu vyberte účet nebo organizaci, do kterých chcete aplikaci nainstalovat.
6. Vyberte buď All repositories, nebo Only select repositories.
7. Klikněte na Install.

Po instalaci Lingo.dev v Settings > GitHub (App) zobrazí připojený účet GitHub a repozitáře. Pokud budete později potřebovat repozitáře přidat nebo odebrat, použijte ve stejné kartě nastavení možnost Manage repositories on GitHub.

Pokud vaše žádost o instalaci čeká na schválení, administrátor GitHubu ji může zkontrolovat na GitHubu v části organizace Settings > 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
    }
  }
}

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.

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 doplnit nebo vynutit překlady konkrétních 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 ...

Ve výchozím nastavení se /lingo translate spouští v režimu doplnění: vytvoří pouze cílové soubory, které ve větvi PR chybí. Pokud chcete znovu vygenerovat existující cílové soubory, přidejte --force.

Podporované formáty#

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

• JSON (.json)
• JSONC (.jsonc)
• Markdown (.md)
• MDX (.mdx)
• Markdoc

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

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

Další kroky#