Traduzir documentos
Envie arquivos de origem e traduções anteriores, inicie uma tarefa de localização e baixe os arquivos resultantes.
Use tarefas de tradução de documentos para traduzir arquivos sem perder a formatação. Uma tarefa pode incluir vários arquivos e idiomas de destino. A API identifica cada arquivo pelo hash SHA-256 de seus bytes exatos.
Você precisa de uma chave de API, um ID de organização e um ID de engine. O guia de localização de arquivos traz um exemplo completo em Node.js.
Escolha um formato #
Defina format.type em cada documento:
| Formato | Tipo |
|---|---|
| JSON / JSONC | json / jsonc |
| Markdown / MDX / Markdoc | md / mdx / markdoc |
| HTML | html |
| TypeScript / PHP | typescript / php |
| YAML / YAML com idioma na raiz / OpenAPI YAML | yaml / yaml-root-key / yaml-openapi |
| Android / Flutter ARB | android / flutter |
| Strings da Apple / dicionários de plurais / catálogos de strings | xcode-strings / xcode-stringsdict / xcode-xcstrings |
| Gettext / XLIFF / SubRip | po / xliff / srt |
| Texto simples | txt |
| Tabela CSV com uma coluna por idioma | csv |
| Propriedades Java | properties |
| Conteúdo do Payload | payload |
As referências de formatos explicam as estruturas e os controles dos arquivos. A API format.options usa o contrato de documento; a configuração da CLI converte os nomes das próprias opções para esse contrato. Por exemplo, a API usa frontmatterFields para Markdown e componentProps para propriedades de componentes. Os seletores de chaves JSON usam JSONPath.
Defina as opções de formato #
Omita format.options para usar os valores padrão. Defina apenas as opções compatíveis com o tipo selecionado:
| Tipo | Opções |
|---|---|
json, jsonc | Opções de JSON: regras de chaves, escopos, contexto, dicas e inserção de idioma. |
typescript, php, yaml, yaml-root-key | lockedKeys, preservedKeys, ignoredKeys (padrão: []); keyScope e termScope são opcionais e, se fornecidos, não podem estar vazios. |
md | frontmatterFields (padrão: ["$.title", "$.description"]); termScope é opcional e, se fornecido, não pode estar vazio. |
mdx, markdoc | Opções de Markdown, mais componentProps (padrão: []). |
html | componentProps (padrão: []), além dos atributos traduzíveis já incluídos no processador. |
xcode-stringsdict | lockedKeys e preservedKeys (padrão: []); termScope é opcional e, se fornecido, não pode estar vazio. |
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapi | termScope é opcional e, se fornecido, não pode estar vazio. |
csv | keyColumn é opcional e indica o cabeçalho da coluna de chaves (padrão: a primeira célula de cabeçalho). |
properties | lockedKeys, preservedKeys, ignoredKeys (padrão: []) e keyScope opcional e não vazio, comparados à chave completa como padrões no formato antigo ou como JSONPath quando um padrão começa com $; termScope opcional e não vazio; lockedPatterns (padrão: []), expressões regulares RE2 mantidas sem tradução nos valores. |
payload, po, xliff, srt, txt | Sem opções adicionais. |
Regras de chaves, escopos de chaves e campos de metadados iniciais usam consultas JSONPath. termScope seleciona unidades de origem inteiras que contenham qualquer um dos termos fornecidos como parte do texto, diferenciando maiúsculas de minúsculas; "cat" pode corresponder a "catalog". Quando um formato aceita tanto keyScope quanto termScope, fornecer ambos seleciona a interseção entre eles. Os dois escopos exigem traduções existentes às quais o conteúdo possa ser mesclado. A seleção e a reutilização dependem do formato, conforme descrito em atualizações incrementais. Essas opções da API diferem do suporte da CLI ao formato --key.
Uma regra de propriedades de componentes contém props, um array não vazio de nomes de propriedades, e, opcionalmente, components, um array não vazio que restringe a regra aos componentes indicados. Se components for omitido, a regra se aplica a qualquer componente. Para MDX:
{
"type": "mdx",
"options": {
"frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
"componentProps": [{ "components": ["Callout"], "props": ["title"] }]
}
}Isso traduz os metadados iniciais selecionados e os títulos literais de Callout, junto com o texto do documento. Consulte a referência do formato para entender o tratamento de código protegido e expressões, além do comportamento de reconstrução.
Crie a tarefa com endereços de artefatos #
Calcule o hash dos bytes exatos que você pretende enviar. Em Node.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");Crie uma tarefa usando o endereço resultante como source do documento:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de"],
"documents": [
{
"key": "messages/en.json",
"format": { "type": "json" },
"source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
]
}Substitua o endereço de exemplo pelo hash calculado. Salve o ID da tarefa retornado. uploads lista os artefatos de entrada que faltam no armazenamento; o conteúdo já armazenado não precisa ser enviado novamente.
Envie os bytes e inicie a tarefa #
Para cada entrada de uploads, envie uma requisição PUT autenticada para o respectivo uploadUrl, com Content-Type: application/octet-stream e os bytes originais no corpo. Envie os arquivos de origem e todos os arquivos anteriores referenciados antes de iniciar a tarefa.
Cada artefato tem um limite de 25 MiB. Uma divergência de hash retorna ArtifactChecksumMismatch; um arquivo acima do limite retorna RequestBodyTooLarge. Calcular o hash de um texto e depois alterar suas quebras de linha antes do envio muda os bytes e faz a verificação falhar.
Chame POST /v2/localization/jobs/:id/start depois que todos os envios forem concluídos com sucesso. O envio de artefatos só é aceito antes do início da tarefa. Consulte o progresso dos destinos da tarefa e baixe os arquivos concluídos pelas URLs retornadas.
Atualize um documento existente #
Mantenha três entradas para uma atualização incremental: a nova origem, a origem anterior e a tradução atual de cada idioma de destino. Forneça:
source: o endereço do artefato da nova origem.previousSource: o endereço da origem usado na revisão anterior.previousTranslations: uma entrada de{ "locale": "de", "artifact": "..." }por tradução disponível.
Inclua as edições humanas feitas localmente nos bytes da tradução anterior que você fornecer. O processador do formato pode reutilizar o conteúdo inalterado e traduzir o que mudou. Para JSON comum, omitir a origem anterior impede a reutilização baseada em conteúdo de origem inalterado. Outros formatos podem incorporar o conteúdo de destino existente conforme suas próprias regras de mesclagem. Mantenha a versão de referência completa quando precisar distinguir uma edição na origem de uma mensagem inalterada.
Uma solicitação com escopo definido por keyScope ou termScope exige uma tradução anterior para cada idioma de destino. JSON, JSONC, TypeScript e PHP geram novamente as strings selecionadas, incluindo aquelas cujos valores de origem não mudaram, e as mesclam ao destino existente. YAML, YAML com idioma na raiz e OpenAPI YAML podem reutilizar o conteúdo selecionado inalterado quando uma origem anterior é fornecida. XCStrings pode reutilizar valores de destino incorporados ou fornecidos mesmo sem uma origem anterior. Portanto, uma unidade selecionada nem sempre gera novo trabalho de tradução.
Forneça ao engine a terminologia ou a regra desejada antes de solicitar uma nova geração e confira a tradução resultante. Para obter uma redação exata, edite a tradução diretamente em vez de depender de uma nova geração para produzir uma frase específica.
Antes de criar uma tarefa posterior, armazene uma versão de referência usando PUT /v2/organizations/:orgId/localization/artifacts/:address, com autenticação e os bytes do arquivo no corpo da requisição. Essa rota exige acesso de tradução a um engine da organização e retorna os metadados do artefato. Aplicam-se o mesmo limite de 25 MiB e as mesmas verificações de hash.
Baixe os resultados primeiro em arquivos temporários. Antes de substituir os arquivos da aplicação, compare os resultados tanto com a revisão de origem enviada quanto com quaisquer edições feitas na tradução desde o envio. Preserve as traduções revisadas explica o workflow correspondente da CLI.