Por Terralíngua

A documentação de API (interface de programação de aplicativos) ajuda os desenvolvedores a entender como solicitar informações, enviar dados e tratar os resultados. A tradução desta documentação exige um cuidado especial: as explicações devem ser acessíveis em outro idioma, enquanto os elementos que identificam ou operam a interface devem permanecer confiáveis. O planejamento da tradução da API define esse limite antes que os arquivos entrem no fluxo de trabalho de localização de idioma.

Um guia traduzido pode ter uma leitura fluida e ainda assim induzir um desenvolvedor ao erro se o nome de um parâmetro mudar, uma condição desaparecer ou um exemplo pertencer a outra versão. A tradução técnica e a localização da documentação abordam as questões linguísticas relacionadas a esses detalhes. A Terralíngua oferece suporte especializado à localização de software e documentação técnica; no entanto, os desenvolvedores do cliente mantêm a responsabilidade pelo comportamento da API, integração e validação de exemplos executáveis.

A tradução de texto de API começa com o leitor

Identifique quem usará o material traduzido e o que essas pessoas precisam realizar. Um engenheiro parceiro que integra um serviço já estabelecido pode precisar de referências precisas aos endpoints, enquanto um novo desenvolvedor pode, adicionalmente, necessitar de um guia de integração e explicações sobre conceitos de autenticação. Defina o nível de conhecimento do público-alvo sobre o produto e a linguagem preferida, sem presumir que todos os desenvolvedores desejam a tradução de todos os termos técnicos.

Faça um inventário do conjunto de publicações existentes, como guias introdutórios, descrições de endpoints, tabelas de parâmetros, instruções de autenticação, tutoriais, exemplos de respostas e notas de resolução de problemas. Uma API, ou interface de programação de aplicativos, pode ser documentada em diversos sistemas. Indique quais materiais estão incluídos e como os leitores poderão navegar entre as páginas traduzidas e as páginas intencionalmente não traduzidas.

Se a primeira versão abranger apenas parte da documentação, escolha uma jornada de leitura completa. Traduzir um tutorial introdutório sem a página de autenticação necessária pode deixar uma lacuna prática. Defina claramente o conteúdo a ser abordado e combine como os links para o material no idioma original serão apresentados. Essa é uma decisão relacionada ao escopo, não um motivo para traduzir todas as páginas de uma só vez.

Como escolher uma versão do original aprovada e de fácil manutenção

Registre a versão da API, a revisão da documentação e as versões relevantes dos exemplos ou do SDK (kit de desenvolvimento de software). Um SDK pode fornecer seus próprios nomes e padrões de uso. Essas versões não precisam compartilhar o mesmo número. Peça ao responsável pelo produto que confirme se os materiais fornecidos são consistentes entre si quanto ao comportamento previsto antes de adotá-los como referência oficial aprovada.

Forneça arquivos de origem editáveis ​​ou uma exportação estruturada, juntamente com uma referência renderizada que mostre a experiência de leitura pretendida. A documentação pode ter origem em Markdown, em um sistema de gerenciamento de conteúdo ou em um arquivo de descrição de API. Explique como as páginas publicadas são geradas e qual original é o oficial. Traduzir uma página gerada automaticamente pode torná-la vulnerável a ser sobrescrita na próxima versão.

Para equipes que utilizam OpenAPI, sua especificação distingue campos descritivos de elementos estruturais, como caminhos, nomes de parâmetros e identificadores de operação. Essa distinção é útil ao definir o escopo da tradução, mas não se trata de um fluxo de trabalho de localização pronto para uso. Solicite ao responsável pela documentação que aprove os campos elegíveis e as exclusões para a versão e as ferramentas em uso.

OpenAPI Specification: definições de estrutura e de campo

Defina um roteiro de produção que sua equipe possa manter. Inclua como confirmar o escopo do arquivo de origem, o processo de revisão e como fornecer uma exportação de texto aprovada com identificadores estáveis ​​ou outro formato de troca compatível. Confirme a compatibilidade utilizando uma amostra representativa. Não presuma que um fornecedor de tradução possa se conectar automaticamente ao seu repositório, executar seu pipeline de documentação ou publicar alterações; atribua essas tarefas explicitamente.

Teste a transferência proposta com uma seleção pequena, porém variada, como uma página explicativa, uma tabela de parâmetros, um bloco de código e um exemplo de resposta. Confirme se o material devolvido pode ser reintegrado sem perda de identificadores ou contexto. Resolva questões de formato e responsabilidade durante este projeto piloto, em vez de descobri-las após a conclusão de cada versão de idioma.

Como separar o texto explicativo dos elementos protegidos

Classifique o conteúdo pela sua função, e não pela sua aparência. Uma palavra em um caminho de endpoint não é um texto comum, mesmo que pareça familiar. Por outro lado, uma descrição armazenada em um arquivo estruturado pode ser destinada a leitores. Crie um mapa de tradução aprovado que identifique trechos traduzíveis, conteúdo protegido e itens que exigem uma decisão.

  • Traduzir o conteúdo conforme acordado: explicações, parágrafos introdutórios, descrições de parâmetros, notas de precaução e títulos para o leitor.
  • Preservar conforme especificado: caminhos de endpoints, métodos HTTP, nomes de parâmetros, nomes de propriedades, identificadores de operação e referências usadas pelas ferramentas.
  • Revise antes de alterar: valores de exemplo, comentários dentro dos exemplos, texto de erro exibido, destinos dos links e rótulos visíveis da interface.
  • Mantenha associados: descrições e seus identificadores, condições e seus valores, exemplos e suas versões documentadas.

Crie uma lista de palavras que não devem ser traduzidas, contendo a grafia exata e o contexto. Inclua nomes de produtos, comandos, marcadores de posição, identificadores que diferenciam maiúsculas de minúsculas, valores de enumeração e quaisquer linhas que devam corresponder a uma resposta ou interface. Um enum, abreviação de enumeração, é um conjunto definido de valores permitidos. Especifique se um termo está protegido em todos os lugares ou apenas quando funciona como um identificador.

Por exemplo, "status" pode ser uma palavra comum em uma frase e também o nome literal de um estado de propriedade. O texto pode explicar seu significado no idioma-alvo, mantendo o nome da propriedade. Evite regras gerais que impeçam a tradução de todas as ocorrências de uma palavra comum, ou uma substituição global que modifique o conteúdo interpretado por máquinas.

Decida como as passagens mistas serão apresentadas aos linguistas. Proteja os identificadores incorporados, mantendo texto suficiente ao redor para que a frase tenha contexto. Preserve os identificadores de conteúdo estáveis ​​para que os revisores possam rastrear uma pergunta até sua origem. Uma lista de fragmentos isolados, sem títulos ou exemplos, muitas vezes constitui um contexto inadequado para decisões técnicas.

Folhas impressas com o escopo da tradução separam o conteúdo explicativo dos identificadores de parâmetros e endpoints destacados.
Ilustração de um exemplo de transferência de tradução, distinguindo o texto explicativo dos identificadores de API protegidos.

Como manter a localização da documentação de endpoints alinhada ao comportamento real

A descrição de um endpoint deve preservar as condições sob as quais uma operação funciona. Verifique as distinções, como informações obrigatórias versus opcionais, omitidas versus mantidas especificamente em branco e disponíveis versus habilitadas. Um tradutor não deve resolver uma aparente inconsistência escolhendo a formulação que soe mais plausível. Peça ao responsável pela API para explicar o comportamento esperado.

Considere este cenário referente a uma página de referência para GET /v2/orders com um parâmetro chamado “include_archived”. A descrição aprovada indica que os pedidos arquivados são incluídos apenas quando o parâmetro é verdadeiro. O endpoint, o nome do parâmetro e o valor literal permanecem inalterados. A frase explicativa foi traduzida, incluindo a condição. Reformular a frase para significar que os pedidos arquivados estão sempre incluídos alteraria o comportamento documentado.

Forneça explicações aprovadas sobre padrões, limites, paginação e condições de erro, sempre que afetarem o texto. Pode haver um limite por solicitação, por conta ou durante um período determinado; a tradução deve preservar essa relação. Não permita que um título ou célula de tabela abreviada remova a especificação que indica aos leitores como um valor deve ser aplicado.

Crie entradas de terminologia que diferenciem os conceitos do produto dos nomes a serem implementados. Uma conta voltada para o cliente, uma identidade de usuário e um cliente de API podem representar coisas diferentes. Forneça aos tradutores definições e exemplos, em vez de apenas uma lista de termos preferenciais. Nos casos em que a interface do produto permanecer em inglês, defina como o guia identificará os controles que os desenvolvedores visualizam.

Este trabalho se cruza com a consistência mais ampla da documentação de software, mas a tarefa específica da API é preservar a conexão entre as explicações humanas e a interface invocável. Mantenha a terminologia compartilhada do produto alinhada, permitindo que o material de referência conserve o protocolo de nomenclatura exigido pelo produto.

Leitura complementar: como alinhar a localização do software e a documentação do usuário

Como tornar a preservação de exemplos de código em uma regra

Defina uma estrutura de regras quanto aos exemplos que devem permanecer inalterados e se os comentários ou anotações explicativas podem ser traduzidos. Comece com amostras aprovadas pelos desenvolvedores. Um revisor linguístico pode identificar uma discrepância entre uma explicação e um exemplo, mas não deve alterar um exemplo executável nem criar uma chamada substituta devido a essa discrepância.

Os comentários precisam de uma regra específica. Podem ajudar os leitores a compreender uma amostra, mas também podem conter diretrizes ou texto utilizados pelas ferramentas. Solicite aos desenvolvedores que identifiquem os comentários que podem ser traduzidos e quaisquer partes protegidas. Preserve a sintaxe executável e os requisitos de formatação, incluindo a indentação onde ela desempenha uma função prática.

Os dados da amostra também requerem classificação. Um nome de exibição pode ser substituído por conteúdo aprovado, enquanto um valor de status ou identificador de recurso pode ser necessário para que o exemplo funcione. Não localize datas, separadores decimais, literais booleanos ou outros valores destinados às máquinas simplesmente porque o idioma-alvo usa convenções diferentes.

JSON (JavaScript Object Notation) possui uma sintaxe definida para linhas, números e literais como true, false e null. Traduzir as explicações complementares não autoriza a alteração dessa sintaxe. Um exemplo de resposta sintaticamente válido ainda pode estar incorreto para a API, portanto, a análise sintática é apenas uma verificação; os desenvolvedores devem confirmar os campos e valores em relação ao comportamento documentado.

RFC 8259: o formato de intercâmbio de dados JSON

Utilize exemplos sintéticos aprovados em vez de credenciais reais ou registros de clientes. Antes da entrega, peça ao responsável que remova informações confidenciais e conteúdo sensível, mantendo o contexto necessário para a tradução. Explique claramente os espaços reservados e as etapas de substituição. Substituir um token real por um fictício não torna, por si só, o restante da solicitação capturada adequada para publicação.

Como explicar exemplos de resposta sem reinventar a roda

Diferencie a resposta retornada pelo serviço da explicação que a acompanha. Se o serviço retornar um texto de erro em inglês, traduzir esse texto dentro de uma suposta resposta real pode implicar uma capacidade linguística que a API não possui. Mantenha a resposta aprovada e traduza a sua explicação, a menos que o responsável pelo produto autorize uma apresentação diferente.

Caso a API suporte conteúdo de resposta localizado, obtenha exemplos aprovados para a configuração de idioma e versão relevantes. A documentação deve descrever esse comportamento com precisão, em vez de produzir resultados localizados. Mantenha os códigos de status, nomes de propriedades e outros elementos protegidos consistentes com a interface real, mesmo quando os valores selecionados para o usuário variarem de acordo com o idioma.

Rotule adequadamente as ilustrações e identifique qualquer simplificação intencional. Uma resposta resumida pode omitir campos para se concentrar em um único conceito, mas os leitores não devem confundi-la com um contrato completo. Solicite ao responsável pela documentação que defina quais exemplos são executáveis, quais são esquemáticos e qual validação é esperada para cada um.

Como preservar a estrutura por meio da extração e publicação

Um pacote de tradução deve preservar a estrutura do documento necessária para a reconstrução. Proteja a marcação, os destinos de referência, os espaços reservados e os limites do código conforme acordado. Não presuma que todas as sequências de caracteres em um arquivo estruturado sejam traduzíveis ou que todas as ocorrências de uma descrição nomeada tenham a mesma finalidade. Revise as regras de extração em relação às amostras reais antes de processar o conjunto completo.

Os títulos traduzidos podem afetar os links âncora gerados automaticamente, dependendo do sistema de publicação. Deixe que a equipe de documentação decida se são necessários identificadores específicos e estáveis ​​e teste a navegação após a integração. Verifique as ligações entre guias, referências de endpoints e versões de idioma, incluindo links intencionais para páginas que não foram traduzidas.

Analise a documentação gerada, não apenas o texto retornado. Procure por tabelas quebradas, identificadores cortados, exemplos ausentes, seleções de idioma incorretas e blocos de código renderizados como parágrafos comuns. Nos casos em que os leitores puderem copiar amostras, confirme se o conteúdo copiado corresponde ao exemplo aprovado. As alterações de apresentação não devem introduzir caracteres nem remover espaços necessários ao exemplo.

Como atribuir separadamente a revisão linguística e a validação do desenvolvedor

Indique um revisor linguístico, um responsável pela documentação e um contato de desenvolvedor que possa resolver questões do comportamento esperado. Uma pessoa pode desempenhar mais de uma função, mas as responsabilidades devem ser claras. A revisão linguística verifica o significado, a terminologia e a legibilidade; a revisão técnica verifica se as descrições, os exemplos e as referências do produto são precisos para a versão aprovada.

  • Aceitação do original: confirme a versão aprovada, os arquivos completos, os limites da tradução e as questões pendentes.
  • Aceitação linguística: verifique condições, terminologia, integridade e consistência no contexto.
  • Aceitação estrutural: verifique conteúdos protegidos, validade do arquivo, links e reconstrução ou compilação bem-sucedida.
  • Aceitação do desenvolvedor: valide as amostras executáveis ​​em um ambiente controlado apropriado e confirme o comportamento esperado.
  • Aceitação da publicação: analise a versão do idioma renderizado e registre a aprovação do pacote de lançamento.

Nem todos os exemplos devem ser feitos com base em um serviço em funcionamento. As chamadas podem criar, alterar ou excluir recursos. Os desenvolvedores devem escolher o ambiente de teste, as credenciais e as verificações apropriadas. A equipe de tradução pode sinalizar possíveis problemas e incorporar as correções aprovadas; não improvise solicitações em tempo real para demonstrar a documentação funcional.

Mantenha as perguntas vinculadas à origem, ao endpoint e à versão. Registre a resposta aprovada e as passagens afetadas. Se um desenvolvedor alterar um exemplo durante a revisão, reavalie a explicação associada em vez de substituir apenas o código. Resolva as questões que afetam a publicação antes de aprovar a versão final do idioma e mantenha as exclusões intencionais no registro de entrega.

Na entrega final, identifique a versão de origem, os idiomas-alvo, os arquivos incluídos, as exclusões acordadas e as tarefas de publicação restantes. Forneça a terminologia aprovada e as decisões de consulta quando estas fizerem parte do escopo. Mantenha o arquivo traduzido junto com o registro da versão para que a próxima atualização possa partir de uma base conhecida, em vez de uma página exportada de origem incerta.

Como planejar atualizações relacionadas a mudanças significativas

Para versões subsequentes, forneça o conjunto de alterações aprovado e contexto suficiente para uma interpretação correta. Uma pequena alteração, mudando algo de "opcional" para "obrigatório", pode ser mais importante do que um novo parágrafo introdutório com mais palavras. Identifique em conjunto as alterações nos endpoints, exemplos e descrições compartilhadas para que a equipe de idiomas possa avaliar o efeito completo, em vez de traduzir palavras isoladas.

Traduções previamente aprovadas podem servir de apoio à consistência, mas a semelhança não comprova a precisão contínua. Verifique se o texto reutilizado corresponde à nova versão e às suas condições. Se a documentação abranger várias versões de API suportadas, mantenha seus registros de tradução distintos. Evite aplicar correções da versão mais recente a uma versão mais antiga cujo comportamento seja intencionalmente diferente.

O esforço depende da qualidade do original, do conteúdo repetido, da sintaxe protegida, dos formatos, do número de idiomas e da complexidade da revisão. Um extenso conjunto de referências com descrições consistentes pode exigir uma preparação diferente de um breve tutorial com muitos exemplos executáveis. Questões não resolvidas sobre o produto e a indisponibilidade de revisores podem atrasar a conclusão, mesmo quando o volume de traduções é modesto.

Como a Terralíngua pode apoiar sua documentação

A Terralíngua oferece serviços de tradução e localização com certificação ISO para interfaces de software e documentação técnica, utilizando o contexto do produto, materiais de referência e terminologia estabelecida pelo setor. Para um projeto de API, discuta o conteúdo explicativo, as referências técnicas relevantes e os formatos de entrega necessários como escopo do trabalho. Um pacote de modelos representativos pode ajudar a estabelecer os requisitos linguísticos e qualquer preparação necessária antes do início do trabalho.

Confirme quem irá extrair o conteúdo, proteger os elementos não traduzíveis, reintegrar os arquivos retornados e elaborar a documentação final. Essas condições dependem do seu ambiente e do escopo de serviço acordado. A automação do repositório, a validação de engenharia e a publicação não devem ser consideradas como certas. Os desenvolvedores e responsáveis ​​pela documentação mantêm a responsabilidade pelo comportamento do software e pelas decisões de lançamento.

Conheça os serviços de localização de software e tecnologia da Terralíngua

Perguntas frequentes

Os nomes dos parâmetros devem ser traduzidos para leitores locais?

Preserve os nomes que os chamadores devem usar. Traduza a explicação do parâmetro, mantendo seu identificador exato reconhecível. Se o produto tiver nomes diferentes em outra interface, peça ao responsável que documente essa distinção em vez de substituir o nome por um nome localizado em um exemplo de API.

Podemos começar exportando para PDF?

Um PDF pode auxiliar na avaliação inicial e fornecer contexto visual. Para um site de documentação mantido, identifique também o original editável e a rota de integração. Definam se o produto final é um documento traduzido independente ou conteúdo destinado a retornar ao sistema de publicação, pois são escopos diferentes.

E se a documentação e a API entrarem em conflito?

Peça ao responsável pelo produto para resolver quaisquer discrepâncias. Não obrigue a equipe de tradução a escolher um comportamento ou a corrigir o texto original. Registre a decisão aprovada, atualize o material de origem relevante e identifique todas as versões de idioma e amostras afetadas antes da publicação.

Como preparar um breve resumo da documentação da API

Para solicitar uma avaliação da Terralíngua, compartilhe um exemplo de documentação aprovada, o formato de origem exigido, as versões da API e da documentação, os idiomas de destino, o público-alvo e o prazo. Inclua a lista de itens que não devem ser traduzidos, exemplos de código e respostas representativas, formatos de saída exigidos e contatos para revisão técnica. Essas informações ajudam a definir um escopo de tradução prático, mantendo o comportamento executável e a aprovação da publicação com sua equipe de desenvolvimento.

Solicite um orçamento para tradução de documentação de API