Traduzir documentos
Carregue ficheiros de origem e traduções anteriores, inicie uma tarefa de localização e descarregue os ficheiros resultantes.
Utilize tarefas de tradução de documentos para traduzir ficheiros sem alterar o seu formato. Cada tarefa pode incluir vários ficheiros e idiomas de destino. A API identifica cada ficheiro pelo hash SHA-256 dos seus bytes exatos.
Precisa de uma chave de API, de um ID de organização e de um ID de motor. O guia de localização de ficheiros apresenta um exemplo completo em Node.js.
Escolher 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 |
| Cadeias de texto da Apple / dicionários de plurais / catálogos de cadeias de texto | 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 dos formatos explicam as estruturas dos ficheiros e os controlos. Na API, format.options utiliza o contrato de documentos; a configuração da CLI converte os seus próprios nomes de opções para esse contrato. Por exemplo, a API utiliza frontmatterFields para Markdown e componentProps para propriedades de componentes. Os seletores de chaves JSON utilizam JSONPath.
Definir opções de formato #
Pode omitir format.options para utilizar os valores predefinidos. Defina apenas as opções suportadas pelo tipo selecionado:
| Tipo | Opções |
|---|---|
json, jsonc | Opções de JSON: regras de chaves, âmbitos, contexto, indicações e injeção de idioma. |
typescript, php, yaml, yaml-root-key | lockedKeys, preservedKeys, ignoredKeys (predefinição: []); keyScope e termScope opcionais, mas não podem estar vazios. |
md | frontmatterFields (predefinição: ["$.title", "$.description"]); termScope opcional, mas não pode estar vazio. |
mdx, markdoc | Opções de Markdown, mais componentProps (predefinição: []). |
html | componentProps (predefinição: []), além dos atributos traduzíveis já integrados no processador. |
xcode-stringsdict | lockedKeys e preservedKeys (predefinição: []); termScope opcional, mas não pode estar vazio. |
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapi | termScope opcional, mas não pode estar vazio. |
csv | keyColumn opcional, que indica o cabeçalho da coluna de chaves (predefinição: a primeira célula do cabeçalho). |
properties | lockedKeys, preservedKeys, ignoredKeys (por predefinição, []) e keyScope opcional, mas não vazio, comparados com a chave completa como padrões de estilo antigo ou como JSONPath quando um padrão começa por $; termScope opcional, mas não vazio; lockedPatterns (por predefinição, []), expressões regulares RE2 que se mantêm sem tradução nos valores. |
payload, po, xliff, srt, txt | Sem opções adicionais. |
As regras de chaves, os âmbitos de chaves e os campos de metadados iniciais utilizam consultas JSONPath. termScope seleciona unidades de origem completas que contenham qualquer um dos termos fornecidos como parte do texto, com distinção entre maiúsculas e minúsculas; "cat" pode corresponder a "catalog". Quando um formato suporta tanto keyScope como termScope, fornecer ambos seleciona a sua interseção. Ambos os âmbitos exigem traduções existentes nas quais integrar o conteúdo. A seleção e a reutilização dependem do formato, conforme descrito em atualizações incrementais. Estas opções da API diferem do suporte da CLI ao formato --key.
Uma regra de propriedades de componentes contém props, uma lista não vazia de nomes de propriedades, e, opcionalmente, components, uma lista não vazia que restringe a regra aos componentes indicados. Se omitir components, a regra aplica-se a qualquer componente. Para MDX:
{
"type": "mdx",
"options": {
"frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
"componentProps": [{ "components": ["Callout"], "props": ["title"] }]
}
}Isto traduz os metadados iniciais selecionados e os títulos literais de Callout, juntamente com o texto corrido do documento. Consulte a referência do formato para saber mais sobre código protegido, expressões e o comportamento de reconstrução.
Criar a tarefa com endereços de artefactos #
Calcule o hash dos bytes exatos que pretende carregar. 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 com 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. Guarde o ID da tarefa devolvido. uploads lista os artefactos de entrada que faltam no armazenamento; não é necessário voltar a carregar conteúdo já armazenado.
Carregar os bytes e iniciar #
Para cada entrada de uploads, envie um pedido PUT autenticado para o respetivo uploadUrl, com Content-Type: application/octet-stream e os bytes originais no corpo do pedido. Carregue os ficheiros de origem e todos os ficheiros anteriores referenciados antes de iniciar a tarefa.
Cada artefacto tem um limite de 25 MiB. Se o hash não corresponder, é devolvido ArtifactChecksumMismatch; se o ficheiro exceder o limite, é devolvido RequestBodyTooLarge. Calcular o hash de um texto e depois alterar as terminações de linha antes do carregamento modifica os bytes e faz com que a verificação falhe.
Chame POST /v2/localization/jobs/:id/start depois de todos os carregamentos terem sido concluídos com êxito. Os carregamentos de artefactos só são aceites antes do início da tarefa. Consulte o progresso da tarefa por idioma de destino e, em seguida, descarregue os ficheiros concluídos a partir dos URLs devolvidos.
Atualizar um documento existente #
Para uma atualização incremental, mantenha três elementos de entrada: a nova origem, a origem anterior e a tradução atual de cada idioma de destino. Forneça:
source: o endereço do novo artefacto de origem.previousSource: o endereço de origem utilizado na revisão anterior.previousTranslations: uma entrada de{ "locale": "de", "artifact": "..." }por tradução disponível.
Inclua as alterações manuais feitas localmente nos bytes da tradução anterior que fornecer. O processador do formato pode reutilizar o conteúdo inalterado e traduzir o conteúdo alterado. No caso de JSON comum, omitir a origem anterior impede a reutilização de conteúdo cuja origem não tenha sido alterada. Outros formatos podem aproveitar o conteúdo de destino existente de acordo com as suas próprias regras de integração. Mantenha a versão de referência completa quando precisar de distinguir uma alteração na origem de uma mensagem inalterada.
Um pedido com âmbito definido através de keyScope ou termScope exige uma tradução anterior para cada idioma de destino. JSON, JSONC, TypeScript e PHP voltam a gerar as cadeias de texto selecionadas, incluindo valores de origem inalterados, e integram-nas no destino existente. YAML, YAML com idioma na raiz e OpenAPI YAML podem reutilizar conteúdo selecionado que não tenha sido alterado quando é fornecida uma origem anterior. XCStrings pode reutilizar valores de destino incorporados ou fornecidos, mesmo sem uma origem anterior. Por isso, uma unidade selecionada nem sempre dá origem a novo trabalho de tradução.
Forneça ao motor a terminologia ou a regra pretendida antes de pedir uma nova geração e verifique o texto de destino resultante. Para obter uma formulação exata, edite diretamente o texto de destino, 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 através de um pedido autenticado a PUT /v2/organizations/:orgId/localization/artifacts/:address, com os bytes do ficheiro no corpo do pedido. Esta rota exige acesso de tradução a um motor da organização e devolve os metadados do artefacto. Aplicam-se o mesmo limite de 25 MiB e as mesmas verificações de hash.
Descarregue primeiro os resultados para ficheiros temporários. Antes de substituir os ficheiros da aplicação, compare os resultados tanto com a revisão de origem enviada como com quaisquer alterações feitas no destino desde o envio. Preservar traduções revistas explica o workflow correspondente da CLI.