GitHub

Překládejte obsah repozitáře pomocí GitHub App a mějte zdrojové změny i výsledné překlady stále k dispozici ke kontrole.

Lingo.dev GitHub App začleňuje přeložené soubory do historie změn vašeho repozitáře. Do repozitáře uložíte commit se zdrojovým obsahem a konfigurací překladu. Aplikace načte vybrané soubory, přeloží je prostřednictvím lokalizačního engine a vrátí diff, který může tým zkontrolovat na GitHubu.

V navigaci Studia 2.5 přejděte na Studio 2.5 → Integrace místo Nastavení → Integrace. Stávající odkazy pro připojení a nastavení fungují i nadále.

Změny ve výchozí větvi vedou k vytvoření pull requestu s překlady. Pokud zapnete zpracování pull requestů, překlady se místo toho přidají do větve příslušného pull requestu. Tato stránka začíná workflow pro výchozí větev a odděluje dodání překladů od rozhodnutí o jejich sloučení. Chcete-li CLI spouštět ve vlastním runneru, použijte návod pro GitHub Actions.

Jak svému programovacímu agentovi umožnit připojení k aplikaci, zjistíte v části Nastavení s programovacím agentem.

Připojte repozitář a nastavte konfiguraci překladu #

V Lingo.dev otevřete Nastavení → Integrace a u GitHubu vyberte Připojit. Propojte instalaci aplikace se svou organizací a udělte jí přístup k repozitářům, které má zpracovávat. Instalaci může být nutné nechat schválit správcem organizace na GitHubu. Přístup k repozitářům se řídí rozsahem zvoleným při instalaci.

V připojené organizaci vyberte dostupný lokalizační engine. Jeho konfigurace určuje výběr modelů, glosář, pravidla, styl komunikace i příslušný způsob kontroly. Oprávnění instalace na GitHubu umožňují práci s repozitářem, zatímco oprávnění v Lingo.dev umožňují používání lokalizačního engine.

V Nastavení → Integrace otevřete připojení a zkontrolujte jeho instalaci a stav. Volba Spravovat na GitHubu otevře nastavení přístupu instalace k repozitářům. V prostředí Studio vyberte repozitář v části Připojené. Konkrétní zdrojovou změnu pak sledujte v části Spuštění workflow spolu s kontrolou na GitHubu a commity.

Pokud má vaše organizace aktivní Studio 2.5, na postranním panelu Zdrojový obsah najdete repozitáře, ke kterým má připojená instalace přístup, bez čekání na událost z GitHubu. S platným .lingo/config.json ve výchozí větvi můžete otevírat nakonfigurované zdrojové soubory JSON a JSONC i jejich stávající překlady bez nového commitu nebo spuštění překladu. Procházení nespotřebovává překladové kredity ani nezapíná automatickou synchronizaci. Repozitáře bez platné konfigurace zůstávají viditelné; při otevření jejich souborů se zobrazí chyba konfigurace.

V kořenovém adresáři repozitáře vytvořte .lingo/config.json. Tento příklad vybírá anglické katalogy JSON v locales/en/ a vytváří francouzské soubory na odpovídajících cestách locales/fr/. Nahraďte eng_example ID svého lokalizačního engine:

json
{
  "engineId": "eng_example",
  "sourceLocale": "en",
  "targetLocales": ["fr"],
  "files": [
    {
      "pattern": "locales/en/**/*.json",
      "format": "json"
    }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": false }
    },
    "safety": { "requireApproval": true }
  }
}

Dokončete jedno spuštění a zkontrolujte výsledek #

Tento příklad vyžaduje schválení před zahájením překladu. Otestujte ho takto:

  1. Do výchozí větve uložte commit s konfigurací a drobnou zdrojovou změnou, například jednou zprávou v locales/en/checkout.json.
  2. Otevřete čekající kontrolu na GitHubu a schvalte spuštění. Pokud schválení není dostupné, projděte si pravidla schvalování.
  3. Otevřete pull request s překlady, který aplikace vytvoří nebo aktualizuje. Najděte locales/fr/checkout.json a porovnejte změněnou zprávu se zdrojem.
  4. Sestavte nebo spusťte aplikaci s přeloženým souborem. Zkontrolujte formulace, proměnné a výběr jazyka. Poté pull request zkontrolujte a slučte obvyklým postupem pro váš repozitář.

Schválení v kroku 2 povoluje provedení překladu a související spotřebu. Neschvaluje výsledné formulace ani neslučuje pull request. Pokud výstup chybí, podle části kontrola a obnovení zjistěte, která fáze zůstala nedokončená.

Přizpůsobte konfiguraci uspořádání souborů #

Vzory pro výběr zdrojů by měly zahrnovat pouze zdrojové soubory. Například locales/en/**/*.json vyloučí vygenerované francouzské soubory z pozdějšího vyhledávání zdrojů. Vzory jsou relativní vůči repozitáři; absolutní cesty a .. nejsou povoleny. Každá položka souboru vyžaduje pattern nebo seznam include. Jedna konfigurace podporuje až 100 položek souborů a 50 jedinečných cílových jazyků.

Ve výchozím nastavení určuje zdrojový jazyk v cestě, kam se uloží cílové soubory. Pokud cesty jazyk neobsahují, nastavte targetPath: [locale] dosadí cílový jazyk a [path] zdrojovou cestu po odebrání případné předpony sourceRoot. Například sourceRoot: "content" a targetPath: "translations/[locale]/[path]" převedou pro francouzštinu cestu content/help/start.md na translations/fr/help/start.md. Šablona založená na vzoru glob vyžaduje oba zástupné symboly. sourceRoot vyžaduje targetPath a musí být předponou cest k vybraným zdrojům. Formáty, které uchovávají více jazyků v jednom souboru, například katalogy řetězců Xcode a CSV, výstupní šablony nepodporují, protože překlady zůstávají v původním souboru.

Použijte localeFormat, pokud aplikace v cestách potřebuje kódy jazyků ve formátu BCP-47, s podtržítky nebo v zápisu pro Android. Prostředky Androidu ve výchozím nastavení používají kvalifikátory Androidu. Než přidáte další jazyky, ověřte, že první výstupní cesta odpovídá způsobu, jakým aplikace soubory načítá.

Zvolte, kdy se překlad spustí a kam se uloží #

Zpracování při odeslání změn do výchozí větve je ve výchozím nastavení aktivní. Zpracování pull requestů je ve výchozím nastavení neaktivní a je nutné ho výslovně zapnout v konfiguraci.

Před zapnutím zpracování pull requestů uložte do výchozí větve commit s platným .lingo/config.json. Aplikace načítá ID engine, github.workflows a github.safety z této důvěryhodné revize výchozí větve. Změny těchto nastavení v pull requestu nepovolují použití jiného engine ani nemění pravidla schvalování pro spuštění daného pull requestu. Zdrojový jazyk, výběr souborů a cílové jazyky se přebírají z překládané revize.

SpouštěčDodání překladu
Odeslání změn do výchozí větveUloží commit do lingo/translations/<default-branch> a otevře nebo aktualizuje pull request směřující zpět do výchozí větve.
Aktivní workflow pro pull requestyUloží výstup překladu jako commit do zdrojové větve pull requestu.
Příkaz k překladu v pull requestuZapíše požadovaný výstup překladu do zdrojové větve daného pull requestu.

Dodání překladu do pull requestu vyžaduje zdrojovou větev s možností zápisu v repozitáři, kde je aplikace nainstalovaná. Aplikace přeskakuje forky a odmítá tento výstup zapisovat přímo do výchozí větve.

Aplikace zpracovává úlohy v repozitáři postupně a filtruje vlastní vygenerované commity, aby opakovaně nespouštěly překlad. Pokud se žádný z nakonfigurovaných zdrojů nezměnil nebo cílové překlady již pokrývají požadovanou práci, může spuštění skončit bez diffu. Výsledek vysvětluje příslušná kontrola. Vynucené opětovné generování slouží k nahrazení vybraných překladů, ne k tomu, aby spuštění beze změn působilo jako aktivní.

Vyžadujte schválení před čerpáním prostředků na překlad #

Výchozí hodnota github.safety.requireApproval je false. Pokud musí někdo spuštění povolit před zahájením překladu, nastavte v konfiguraci výchozí větve hodnotu true. Při odeslání změn do výchozí větve se u kontroly zobrazí tlačítka Schválit a Zamítnout. U pull requestů aplikace zveřejní komentář a oprávněná osoba provádějící kontrolu odpoví pomocí /lingo approve.

Pokud je vyžadováno schválení a auditní kontrolu se nepodaří vytvořit, workflow se zablokuje. Před dalším pokusem o schválení vyřešte problém s vytvořením kontroly nebo s přístupem.

Každý příkaz /lingo translate, se vzory glob pro soubory i bez nich, povoluje požadovanou práci a obchází toto předběžné schválení. Před jeho zveřejněním zkontrolujte rozsah souborů a jazyků.

Spouštějte příkazy v pull requestu #

Přidejte komentář k otevřenému pull requestu, jehož větev patří do repozitáře s nainstalovanou aplikací a není výchozí větví. Aplikace načte první řádek komentáře začínající na /lingo. Zdrojový jazyk, možnosti souborů a cílové jazyky převezme z konfigurace ve zdrojové větvi pull requestu, zatímco engine a bezpečnostní nastavení načte z výchozí větve. Překlad může spustit pouze osoba s oprávněním k zápisu do repozitáře.

PříkazVýsledek
/lingo nebo /lingo helpOdpoví seznamem příkazů.
/lingo translatePřeloží zdrojové změny v tomto pull requestu a zachová nezměněné překlady. Nahradí návrh překladu, který od posledního odeslání změn stále čeká na schválení.
/lingo translate --locales fr,esPřeloží zdrojové změny tohoto pull requestu pouze do uvedených jazyků.
/lingo translate <glob>...Vytvoří chybějící cílové soubory pro nakonfigurované zdroje odpovídající vzorům glob.
/lingo translate <glob>... --forceZnovu vygeneruje odpovídající cílové soubory a nahradí stávající překlady. --force vyžaduje alespoň jeden vzor glob.
/lingo translate [<glob>...] --key <pattern>Znovu přeloží odpovídající pojmenované klíče ve stávajících překladech.
/lingo approveSchválí návrh překladu čekající v tomto pull requestu.

Bez vzorů glob nebo --key příkaz pracuje se soubory, které pull request změnil, takže se spustí i při neaktivním zpracování pull requestů v konfiguraci. Se vzory glob pracuje se soubory ve větvi bez ohledu na změny v pull requestu. Vzory glob jsou relativní vůči kořenovému adresáři repozitáře, rozlišují velká a malá písmena a zahrnují pouze soubory vybrané pomocí nakonfigurovaného pattern. --locales přijímá seznam oddělený čárkami. Kódy se porovnávají s nakonfigurovanými cílovými jazyky bez ohledu na velikost písmen a odpověď upozorní na každý kód, který žádnému z nich neodpovídá.

Části Doplňte vybraný soubor nebo jazyk a Znovu přeložte klíče s kontextem podrobně popisují varianty se vzory glob a klíči.

Doplňte vybraný soubor nebo jazyk #

V pull requestu zveřejněte příkaz omezený na jeden nakonfigurovaný soubor a jazyk:

text
/lingo translate locales/en/checkout.json --locales fr

U formátů se samostatným souborem pro každý jazyk se tím doplní chybějící francouzský cílový soubor. Chybějící klíče uvnitř stávajícího cílového souboru se nedoplní. Přidáním --force se vybraný výstup znovu vygeneruje bez využití stávajícího cílového souboru, takže může přepsat schválené ruční úpravy. Výběr souborů a jazyků co nejvíce omezte a poté zkontrolujte výsledný diff.

Katalogy řetězců Xcode a soubory CSV uchovávají zdrojový i cílový obsah v jednom souboru. Běžný příkaz s vymezeným rozsahem doplní chybějící položky pro jednotlivé jazyky a zachová stávající položky, včetně těch, jejichž zdroj se změnil. Chcete-li přeložit změny zdrojového obsahu v pull requestu, použijte /lingo translate bez vzoru pro výběr souborů; stávající překlady změněných položek se tím mohou nahradit, a to i včetně ručních úprav. Pokud chcete stávající překlady vygenerovat znovu, přidejte --force a úzce vymezte výběr souborů a jazyků. Vynucený příkaz aplikace znovu sestaví vybraný obsah a zachová přitom jazyky mimo požadovaný rozsah. Při aktualizacích přes CLI postupujte podle pokynů k opravám v části Katalogy řetězců nebo CSV.

Znovu přeložte klíče s kontextem #

Pomocí --key znovu přeložíte vybrané pojmenované klíče ve stávajících překladech. U souborů JSON a JSONC přidejte --context, abyste vysvětlili jejich význam nebo pro toto spuštění upřesnili tón a psaní velkých a malých písmen:

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

--context vyžaduje --key. Kontext zadejte jednou; použije se pro každý vybraný klíč a jazyk v souborech JSON a JSONC. Ostatní odpovídající formáty se přeloží bez tohoto kontextu. Pro více vzorů zopakujte --key a požadavek omezte pomocí vzorů glob pro soubory nebo --locales. Bez vzorů glob pro soubory příkaz vybere všechny nakonfigurované zdrojové soubory. Klíče se vybírají podle přesné shody, předpony nebo vzoru glob; nesouvisející překlady zůstanou zachovány. Formáty bez pojmenovaných klíčů a jazyky bez stávajících překladů se přeskočí.

Příkazy GitHub App zaměřené na klíče znovu generují vybrané nezměněné řetězce také v YAML a v YAML s jazyky na kořenové úrovni. Workflow CLI omezené na klíče u těchto formátů využívá výchozí stav jinak.

Příkaz zapište na jeden řádek. Kontext obsahující mezery uzavřete do jednoduchých nebo dvojitých uvozovek; funguje také --context="button label". Chcete-li uvnitř textu použít stejnou uvozovku, vložte před ni zpětné lomítko, například --context "Use \"Save\" as a button label". Kontext se uchovává u spuštění pro opakované pokusy a historii, ale neukládá se jako instrukce pro engine ani se nepřenáší do dalších spuštění. Stávající pravidla pro glosář, zástupné symboly a výstupní formát platí i nadále.

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

Chraňte obsah, který se nemá měnit #

Aplikace podporuje strukturované katalogy, dokumenty ve formátech vycházejících z Markdownu, HTML, titulky, prostý text, tabulky CSV, soubory vlastností Java a prostředky jednotlivých platforem. Jednotlivé moduly pro zpracování popisuje sekce Formáty. Payload nepatří mezi formáty souborů, které lze v integraci GitHub vybrat.

HTML vyberte pomocí vzorů jako pages/en/**/*.html a pages/en/**/*.htm; z obou přípon se automaticky odvodí html a lze také výslovně zadat "format": "html". Výstup HTML vkládá přeložený text a vybrané atributy do zdroje a zachovává ostatní značky, komentáře i formátování. Výslovně uvedený prvek <html> dostane cílový jazyk v lang; k fragmentům se nepřidávají obalové prvky dokumentu.

Soubory s prostým textem vyberte pomocí vzoru, který končí na .txt, například metadata/en/*.txt, nebo pomocí "format": "txt". Soubor .txt spadá pouze pod takovou položku a položka s "format": "txt" vybírá jen soubory .txt. Obecný vzor jako docs/en/**/* tak přeskočí LICENSE.txt a obecná položka txt přeskočí obrázky uložené spolu s textem. Prostý text překládá každý řádek přímo na původním místě.

Soubory CSV vybírejte stejným způsobem: pomocí vzoru končícího na .csv, například i18n/strings.csv, nebo pomocí "format": "csv". Soubor .csv patří pouze k takové položce a položka s "format": "csv" vybírá pouze soubory .csv. CSV vyplní ve zdrojovém souboru sloupce pro cílové jazyky.

Soubory vlastností Java vyberte stejným způsobem: pomocí vzoru končícího na .properties, například src/main/resources/messages_en.properties, nebo pomocí "format": "properties", aby obecný vzor jako src/main/resources/**/* vynechal application.properties. Ze zdrojového souboru s názvem messages_en.properties vzniknou cílové soubory jako messages_de.properties. Modul Vlastnosti Java překládá každou hodnotu přímo na jejím místě, zachovává komentáře i rozložení a rozpoznává lockedKeys, preservedKeys, ignoredKeys a lockedPatterns stejně jako předchozí CLI.

U dokumentu vyberte pole frontmatter a vlastnosti komponent, které obsahují přeložitelný text. U katalogu podobného JSON použijte uzamčené cesty ke kopírování zdrojových hodnot, zachovávané cesty k ponechání stávajících cílových hodnot a ignorované cesty k vynechání hodnot z výstupu. Katalog tak může obsahovat text spolu s identifikátory a odkazy, aniž by se při překladu se vším zacházelo stejně. Vkládání jazyka zapíše cílový jazyk do nakonfigurovaného výstupního pole.

Možnosti položek souborů #

Následující pole umístěte přímo do objektu v poli files souboru .lingo/config.json, nikoli pod options. Aplikace přísně ověřuje kořenová pole, položky souborů, nastavení GitHubu, pravidla komponent a objekty pro vkládání jazyka. Nepovinnou sekci i18n ignoruje a povoluje v ní další pole. Strojově čitelné schéma najdete na GET https://api.lingo.dev/github-app/schema.json.

PolePovolený tvarVýchozí hodnota nebo rozsah
pattern / includeNeprázdný řetězec s cestou relativní vůči repozitáři / neprázdné pole takových řetězců.Alespoň jedno je povinné; zadané include má přednost před pattern. Vzory nesmějí začínat na / ani obsahovat ...
excludePole neprázdných vzorů relativních vůči repozitáři.Nepovinné; platí pro tuto položku.
formatŘetězec určující formát, včetně "html".Nepovinné, lze odvodit automaticky; .html a .htm vybírají HTML. Payload nelze vybrat. Nejde o objekt {type,options} dokumentu.
localeFormat"bcp47", "underscore" nebo "android".Standardní výchozí hodnota je BCP-47; formát Android používá zápis pro Android.
targetPath, sourceRootNeprázdné řetězce s cestami relativními vůči repozitáři.Nepovinné; platí výše uvedená pravidla pro výstupní šablony.
lockedKeys, preservedKeys, ignoredKeysPole neprázdných řetězců cest ke klíčům v tečkové nebo závorkové notaci.Při vynechání se použije []; účinek závisí na modulu pro zpracování formátu. Nejde o přímé volby JSONPath pro dokument.
injectLocaleLogická hodnota nebo { "enabled": boolean, "key"?: nonempty string }.Při vynechání je vkládání vypnuté; při zapnutí se použije výchozí hodnota language, pokud chybí key.
translateFrontmatterFieldsPole neprázdných řetězců.U dokumentů ve formátech vycházejících z Markdownu se při vynechání vyberou title, description; [] nevybere nic.
translateComponentPropsPole neprázdných řetězců s názvy vlastností nebo objektů s nepovinným component a povinným neprázdným polem props.component je neprázdný řetězec nebo neprázdné pole neprázdných řetězců; při vynechání se filtr názvů nepoužije. Výchozí hodnota pole je [].

Například položka JSON může kromě pattern obsahovat i "lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" }. Položka Markdoc může pomocí "translateComponentProps": [{ "component": "Callout", "props": ["title"] }] vybrat titulek komponenty. CLI přijímá některé prázdné hodnoty a u některých neznámých polí pouze zobrazí upozornění, zatímco aplikace je odmítá. Konfiguraci aplikace proto ověřujte podle tohoto schématu.

Zkontrolujte a obnovte první opakované spuštění #

Pomocí kontroly na GitHubu a části Spuštění workflow zjistěte repozitář, zdrojovou revizi, lokalizační engine, vybrané soubory, jazyky a větev pro uložení výstupu. Porovnejte je s očekávanou změnou a poté určete, kde se zpracování zastavilo:

ZjištěníCo zkontrolovat před vyžádáním další práce
Konfigurace výchozí větve chybí, je neplatná nebo vypíná workflowNa GitHubu se nezobrazí žádná kontrola ani komentář. Opravte .lingo/config.json ve výchozí větvi včetně požadovaného nastavení workflow a uložte změny jako commit.
Kontroly výchozí větve proběhly úspěšně, ale konfigurace zdrojové revize chybí nebo je neplatnáSpuštění ohlásí neúspěšnou kontrolu a u příslušného workflow pro PR přidá také komentář. Opravte nahlášenou chybu konfigurace zdrojů.
Žádné odpovídající zdrojové změny nebo požadované překlady již existujíZkontrolujte vzory a pokrytí vybraných překladů; spuštění bez provedených změn neznamená neúspěšný překlad.
Dříve vynechaná zdrojová změna v PRPři synchronizaci PR může workflow porovnat stav se základní revizí PR a doplnit práci vynechanou při porovnání s bezprostředně předchozím zdrojem. Zkontrolujte společně základní a aktuální zdroj i cílový překlad.
Ruční úprava cílového překladu v PRU formátů se samostatnými cílovými soubory chrání běžné zpracování změn v PR cílový soubor upravený oproti základní revizi, pokud autorem jeho posledního commitu není bot. Zkontrolujte tuto úpravu a nepovažujte přeskočený výstup automaticky za chybějící práci.
Před pozdějším selháním již vznikly některé commityVýstup se může ukládat do commitů po dávkách. K jednomu spuštění může patřit několik commitů a selhání pozdější dávky nevrátí zpět předchozí úspěšné commity. Cesty s již dodaným výstupem a zbývající chyby kontrolujte odděleně.

Výstup se seskupuje do commitů s limitem 100 souborů a velikostním prahem 5 MiB pro seskupování. Při pozdějším selhání mohou dřívější commity zůstat zachované. Než spuštění zopakujete nebo vrátíte jeho změny, zkontrolujte cesty s již dodaným výstupem a zbývající chyby.

Chcete-li zastavit opakované zpracování, vypněte příslušné spouštěče. Pokud již aplikace nemá mít oprávnění k repozitáři, odeberte jí k němu přístup nebo ji na GitHubu odinstalujte. Stávající commity, přijaté pull requesty i dosavadní spotřeba zůstanou zachovány. Dodaný obsah ponechte nebo vraťte zpět obvyklým postupem pro váš repozitář.

Shromažďujte aktivitu v Radaru #

Připojení také předává Radaru aktivitu commitů z GitHubu. Část Shromažďování překladů pro měření popisuje nastavení událostí a postup, jak před spuštěním měření za minulé období importovat historii poskytovatele.