CSV

Překládejte tabulku CSV, ve které má každý jazyk vlastní sloupec v jednom souboru a řádky identifikuje klíč ze sloupce, který si zvolíte.

Překladová tabulka CSV uchovává zdrojový text i všechny překlady v jednom souboru: každá zpráva má svůj řádek a každý jazyk svůj sloupec. Modul pro zpracování souborů csv vyplní buňky cílových jazyků a výsledek zapíše zpět na původní cestu. Zapisuje pouze do buněk cílových jazyků, a pokud některému jazyku sloupec chybí, přidá ho, jak popisuje část Které řádky se překládají. Ostatní sloupce, pořadí řádků, uvozovky i konce řádků zůstávají beze změny. Značka pořadí bajtů UTF-8 na začátku souboru se nezachovává: výsledný soubor ji neobsahuje. Pokud tedy tabulkový procesor tuto značku potřebuje k rozpoznání UTF-8, může být nutné soubor importovat s výslovně zvoleným kódováním UTF-8.

Uspořádání tabulky #

Záhlaví tvoří první řádek, který není prázdný a neobsahuje jen bílé znaky. Jeden sloupec obsahuje klíč identifikující každý řádek, další zdrojový text a každý cílový jazyk má vlastní sloupec:

csv
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,
  • Sloupce jazyků. Sloupec patří k určitému jazyku, pokud jeho záhlaví odpovídá kódu tohoto jazyka bez ohledu na velikost písmen: de i DE označují sloupec pro němčinu, ale de-DE označuje jiný jazyk. Záhlaví zdrojového sloupce určuje hodnota sourceLocale ve vaší konfiguraci.
  • Sloupec klíčů. Ve výchozím nastavení určuje název sloupce klíčů první buňka záhlaví. Chcete-li použít jiný sloupec, nastavte keyColumn v konfigurační položce souboru. Sloupcem klíčů může být i samotný zdrojový sloupec, pokud zdrojový text slouží jako klíč.
  • Ostatní sloupce. Sloupce, které neobsahují klíče ani nepatří k žádnému jazyku, například notes, se zachovávají bajt po bajtu a nikdy se neodesílají k překladu.
  • Syntaxe. Buňky jsou oddělené čárkami. Buňka obsahující čárku, uvozovku nebo zalomení řádku se uzavírá do dvojitých uvozovek a každá uvozovka uvnitř se zapisuje dvakrát (""). Soubory s hodnotami oddělenými středníkem nebo tabulátorem nejsou podporovány.

Nastavení překladu CSV #

Soubor CSV vybere pouze konfigurační položka souborů, jejíž vzor končí na .csv a formát se tak odvodí automaticky, nebo položka, která nastavuje "format": "csv". Položka s "format": "csv" vybírá pouze soubory .csv. Obecný vzor, například data/**/*, bez nastavení tohoto formátu soubor CSV nikdy nevybere. Stávající položka tak nezačne přepisovat nesouvisející datové soubory. U přípony se rozlišuje velikost písmen: soubor s názvem strings.CSV se nepřeloží, proto ho přejmenujte na strings.csv.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}

Pro každý jazyk se výsledek zapisuje do téhož souboru, proto tento formát nepovoluje targetPath. Řádky CSV se neporovnávají s pravidly pro klíče, takže nejsou povoleny ani lockedKeys, preservedKeys a ignoredKeys. Stejná konfigurace funguje v CLI i v GitHub App.

Které řádky se překládají #

ŘádekVýsledek
Klíč a zdrojový textPřeloží se pro jazyky, jejichž buňka je prázdná nebo neaktuální.
Klíč, prázdná buňka zdrojového textuZůstává beze změny; buňky jednotlivých jazyků se nemění.
Zdrojový text, buňka klíče prázdná nebo obsahující jen mezeryZůstává beze změny a nepřekládá se. Chcete-li ho přeložit, přiřaďte mu klíč.
Prázdný klíč i zdrojový text nebo prázdný řádekZůstává beze změny, a to i v případě řádku obsahujícího jen mezery.

Buňka daného jazyka obsahující jen mezery se považuje za prázdnou. Vyplněná buňka se použije znovu, pokud se zdrojový text jejího řádku od posledního odeslání nezměnil. Když se zdrojový text řádku změní, buňky všech jazyků v tomto řádku se přeloží znovu. U řádku přidaného od posledního odeslání se vyplněné buňky zachovají a přeloží se jen ty prázdné; za nově přidaný se považuje i řádek se změněným klíčem. Vyplněné buňky se zachovávají také při prvním odeslání souboru, při použití --force v CLI, při použití příkazu GitHub App, který uvádí soubory bez --force, a tehdy, když dříve odeslaný soubor neobsahuje právě jeden zdrojový sloupec nebo právě jeden sloupec klíčů pro porovnání, například po přejmenování některého z nich. Příkaz GitHub App s --force znovu přeloží všechny řádky souboru.

Následující zdrojový text se místo překladu zkopíruje: text tvořený pouze číslicemi ASCII od 0 do 9, například 100; URL, která začíná na // nebo má schéma tvořené písmeny, číslicemi či podtržítky, po němž následuje ://, a jejíž adresa za // začíná na localhost nebo obsahuje alespoň jeden znak, tečku a alespoň dva další znaky, například https://lingo.dev/docs; ID o délce 22 znaků tvořené pouze písmeny a číslicemi, které obsahuje alespoň jedno velké písmeno, jedno malé písmeno a jednu číslici; a datum nebo datum a čas ve formátu ISO 8601, například 2024-01-15 nebo 2024-01-15T10:00:00Z. Zdrojový text se zapíše do všech buněk pro cílové jazyky v daném řádku a nahradí jejich obsah. Řádek se neodešle k překladu ani se za něj nic neúčtuje. Ostatní hodnoty, například 1.5, 100%, e-mailová adresa nebo datum v jiném formátu, například 15.01.2024, se přeloží. Přeloží se také odkazy mailto: a tel:, URL, jejichž schéma obsahuje jiné znaky, například git+ssh://, a URL, jejichž adresa nezačíná na localhost a neobsahuje tečku splňující uvedenou podmínku, například https://intranet nebo https://a.b.

Pokud cílový jazyk nemá vlastní sloupec, přidá se na konec záhlaví. Více nových sloupců se přidává v abecedním pořadí podle kódů jazyků. Každý řádek se pak doplní prázdnými buňkami, aby měly všechny řádky stejný počet buněk. Pořadí řádků se nikdy nemění a žádné řádky se nepřidávají ani neodstraňují.

Chyby #

Zpracování souboru skončí chybou ještě předtím, než se cokoli přeloží nebo naúčtuje. Chybová zpráva uvede příčinu, pokud:

  • v záhlaví chybí nakonfigurovaný keyColumn nebo je první buňka záhlaví prázdná a není nastaveno keyColumn;
  • dva řádky mají stejný klíč, protože by se jejich překlady zapsaly do nesprávných řádků;
  • v záhlaví chybí sloupec pro zdrojový jazyk;
  • sloupec klíčů je zároveň sloupcem některého cílového jazyka;
  • záhlaví uvádí nakonfigurovaný keyColumn, zdrojový jazyk nebo některý cílový jazyk více než jednou;
  • řádek obsahuje více buněk než záhlaví;
  • buňka otevřená uvozovkou není uzavřená;
  • za uzavírací uvozovkou ve stejné buňce následuje text.

Opravte soubor a znovu ho odešlete. CLI vypíše zprávu jednou pod daným souborem, ne pro každý jazyk zvlášť. Pokud selže celý běh, zpráva se zopakuje v závěrečném řádku Run failed:. GitHub App ji zobrazí ve výsledku běhu kontroly.

Oprava existujícího překladu #

Chcete-li překlad změnit na konkrétní znění, upravte přímo buňku. Chcete-li jeden překlad vygenerovat znovu, vymažte obsah dané buňky, zbytek řádku ponechte beze změny a spusťte běžné odeslání:

sh
lingo push --wait

Příkaz CLI --force znovu použije vyplněné buňky stejně jako u katalogů řetězců Apple. Pomocí --key nelze omezit rozsah zpracování souboru CSV: CLI zastaví odesílání s chybou a GitHub App soubor přeskočí. Příkaz CLI purge soubor přeskočí, protože zdroj i výstup mají stejnou cestu. Před vytvořením commitu zkontrolujte všechny změny v souboru.