Překlad dokumentů

Nahrajte zdrojové soubory a předchozí překlady, spusťte lokalizační úlohu a stáhněte si výsledné soubory.

Pomocí dokumentových úloh můžete překládat soubory a zachovat přitom jejich formát. Jedna úloha může zahrnovat více souborů i cílových jazyků. API každý soubor adresuje pomocí hashe SHA-256 vypočteného z jeho přesného bajtového obsahu.

Potřebujete klíč API, ID organizace a ID engine. Průvodce lokalizací souborů obsahuje kompletní příklad v Node.js.

Vyberte formát #

U každého dokumentu nastavte format.type:

FormátTyp
JSON / JSONCjson / jsonc
Markdown / MDX / Markdocmd / mdx / markdoc
HTMLhtml
TypeScript / PHPtypescript / php
YAML / YAML s jazyky na kořenové úrovni / OpenAPI YAMLyaml / yaml-root-key / yaml-openapi
Android / Flutter ARBandroid / flutter
Řetězce Apple / slovníky množných čísel / katalogy řetězcůxcode-strings / xcode-stringsdict / xcode-xcstrings
Gettext / XLIFF / SubRippo / xliff / srt
Prostý texttxt
Tabulka CSV se sloupcem pro každý jazykcsv
Soubory properties jazyka Javaproperties
Obsah Payloadpayload

Referenční dokumentace formátů popisuje struktury souborů a možnosti nastavení. API format.options používá datový kontrakt dokumentu; konfigurace CLI do tohoto kontraktu převádí vlastní názvy voleb. API například používá frontmatterFields pro Markdown a componentProps pro vlastnosti komponent. Selektory klíčů JSON používají JSONPath.

Nastavte volby formátu #

Pokud format.options vynecháte, použijí se výchozí hodnoty. Nastavte pouze volby, které vybraný typ podporuje:

TypVolby
json, jsoncVolby JSON: pravidla pro klíče, rozsahy, kontext, pokyny a vkládání jazyka.
typescript, php, yaml, yaml-root-keylockedKeys, preservedKeys, ignoredKeys (výchozí hodnota []); nepovinné keyScope a termScope, které nesmějí být prázdné.
mdfrontmatterFields (výchozí hodnota ["$.title", "$.description"]); nepovinné termScope, které nesmí být prázdné.
mdx, markdocVolby pro Markdown a navíc componentProps (výchozí hodnota []).
htmlcomponentProps (výchozí hodnota []) vedle atributů, které obslužný modul standardně označuje k překladu.
xcode-stringsdictlockedKeys a preservedKeys (výchozí hodnota []); nepovinné termScope, které nesmí být prázdné.
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapiNepovinné termScope, které nesmí být prázdné.
csvNepovinné keyColumn, záhlaví sloupce s klíči (výchozí hodnota: první buňka záhlaví).
propertieslockedKeys, preservedKeys, ignoredKeys (výchozí hodnota []) a nepovinné neprázdné keyScope, které se porovnávají s celým klíčem jako vzory ve starém formátu, nebo jako JSONPath, pokud vzor začíná na $; nepovinné neprázdné termScope; lockedPatterns (výchozí hodnota []), regulární výrazy RE2, které se v hodnotách ponechávají bez překladu.
payload, po, xliff, srt, txtŽádné další volby.

Pravidla pro klíče, rozsahy klíčů a pole metadat v záhlaví používají dotazy JSONPath. termScope vybírá celé zdrojové jednotky, které obsahují kterýkoli ze zadaných výrazů jako podřetězec, přičemž rozlišuje velká a malá písmena; "cat" tak může odpovídat "catalog". Pokud formát podporuje keyScope i termScope, zadáním obou se vybere jejich průnik. Oba rozsahy vyžadují existující překlady, do kterých se výsledky sloučí. Výběr a opětovné použití obsahu závisí na formátu, jak popisuje část přírůstkové aktualizace. Tyto volby API se liší od podpory formátu --key v CLI.

Pravidlo pro vlastnosti komponent obsahuje props, neprázdné pole názvů vlastností, a nepovinné components, neprázdné pole omezující platnost pravidla na komponenty se zadanými názvy. Pokud components vynecháte, pravidlo se použije na libovolnou komponentu. Pro MDX:

json
{
  "type": "mdx",
  "options": {
    "frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
    "componentProps": [{ "components": ["Callout"], "props": ["title"] }]
  }
}

Tím se spolu s běžným textem dokumentu přeloží vybraná metadata v záhlaví a titulky Callout zadané jako literály. Podrobnosti o chráněném kódu, výrazech a způsobu rekonstrukce najdete v referenční dokumentaci formátu.

Vytvořte úlohu s adresami artefaktů #

Vypočítejte hash přesného bajtového obsahu, který chcete nahrát. V Node.js:

js
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");

Vytvořte úlohu a výslednou adresu použijte jako source dokumentu:

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "documents": [
    {
      "key": "messages/en.json",
      "format": { "type": "json" },
      "source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

Nahraďte ukázkovou adresu vypočteným hashem. Uložte si vrácené ID úlohy. uploads uvádí vstupní artefakty, které v úložišti chybí; již uložený obsah není nutné nahrávat znovu.

Nahrajte bajty a spusťte úlohu #

Pro každou položku uploads odešlete autentizovaný požadavek PUT na její uploadUrl s Content-Type: application/octet-stream a původními bajty v těle požadavku. Před spuštěním nahrajte zdrojové soubory i všechny odkazované předchozí soubory.

Každý artefakt může mít nejvýše 25 MiB. Při neshodě hashe se vrátí ArtifactChecksumMismatch; při překročení maximální velikosti souboru se vrátí RequestBodyTooLarge. Pokud vypočítáte hash textu a před nahráním změníte jeho konce řádků, změní se bajtový obsah a ověření selže.

Jakmile se vše úspěšně nahraje, zavolejte POST /v2/localization/jobs/:id/start. Artefakty lze nahrávat pouze před spuštěním úlohy. Zjistěte průběh úlohy pro cílové jazyky a poté stáhněte dokončené soubory z vrácených URL.

Aktualizujte existující dokument #

Pro přírůstkovou aktualizaci si uchovejte tři vstupy: nový zdroj, předchozí zdroj a aktuální překlad pro každý cílový jazyk. Zadejte:

  • source: adresu artefaktu s novým zdrojem.
  • previousSource: adresu zdroje použitého pro předchozí revizi.
  • previousTranslations: jednu položku { "locale": "de", "artifact": "..." } pro každý dostupný překlad.

Do bajtového obsahu předchozího cílového souboru, který předáváte, zahrňte i ruční úpravy. Obslužný modul formátu může nezměněný obsah znovu použít a změněný obsah přeložit. U běžného JSON vynechání předchozího zdroje znemožní opětovné použití překladů na základě nezměněného zdroje. Ostatní formáty mohou převzít existující cílový obsah podle vlastních pravidel slučování. Pokud potřebujete odlišit úpravu zdroje od nezměněného řetězce, uchovejte úplnou výchozí verzi.

Požadavek s rozsahem omezeným pomocí keyScope nebo termScope vyžaduje předchozí překlad pro každý cílový jazyk. JSON, JSONC, TypeScript a PHP znovu vygenerují vybrané řetězce, včetně těch s nezměněnými zdrojovými hodnotami, a sloučí je s existujícím cílovým obsahem. YAML, YAML s jazyky na kořenové úrovni a OpenAPI YAML mohou znovu použít nezměněný vybraný obsah, pokud předáte předchozí zdroj. XCStrings může znovu použít vložené nebo předané cílové hodnoty i bez předchozího zdroje. Vybraná jednotka proto nemusí vždy vyžadovat nový překlad.

Před požadavkem na nové vygenerování předejte engine požadovanou terminologii nebo pravidlo a poté zkontrolujte výsledný cílový obsah. Pokud potřebujete upravit text na přesné znění, upravte cílový obsah přímo. Nebudete tak záviset na tom, zda nové generování vytvoří konkrétní formulaci.

Před vytvořením další úlohy uložte výchozí verzi pomocí autentizovaného požadavku PUT /v2/organizations/:orgId/localization/artifacts/:address s bajty souboru v těle. Tento koncový bod vyžaduje oprávnění k překladu pro některý engine v organizaci a vrací metadata artefaktu. Platí stejný limit 25 MiB i stejné kontroly hashe.

Výsledky nejprve stáhněte do dočasných souborů. Než jimi nahradíte soubory aplikace, porovnejte je s odeslanou revizí zdroje i se všemi úpravami cílového obsahu provedenými od odeslání. Část Zachování zkontrolovaných překladů popisuje odpovídající workflow v CLI.