Como criar e usar glossários (Advanced)

O glossário é um dicionário personalizado que a API Cloud Translation usa para traduzir com consistência a terminologia específica do domínio do cliente. Isso normalmente envolve a especificação de como traduzir uma entidade nomeada.

Os casos de uso do glossário incluem:

Nomes de produtos: por exemplo, "Google Home" precisa ser traduzido como "Google Home".
Palavras ambíguas: por exemplo, em inglês, a palavra "bat" pode significar um equipamento esportivo ou um animal. Se você souber que está traduzindo palavras sobre esportes, convém usar um glossário para fornecer à API Cloud Translation a tradução de "bat" no contexto esportivo, e não o nome do animal.
Palavras emprestadas: por exemplo, "bouillabaisse" em francês também é "bouillabaisse" em inglês. O inglês tomou de empréstimo a palavra "bouillabaisse" do francês no século 19. Um falante de inglês sem o contexto cultural francês pode não saber que "bouillabaisse" é um prato típico de ensopado de peixe. Os glossários podem substituir uma tradução para que "bouillabaisse" em francês seja traduzida como "fish stew" (ensopado de peixe) em inglês.

Antes de começar

Antes de começar a usar a API Cloud Translation, é preciso ter um projeto em que ela esteja ativada e as credenciais apropriadas. Você também pode instalar bibliotecas de cliente para linguagens de programação comuns para ajudá-lo a fazer chamadas para a API.

Para ver mais informações, consulte a página Configuração.

Permissões necessárias

Para trabalhar com glossários, sua conta de serviço requer permissões específicas de glossário. É possível conceder um papel à sua conta de serviço usando um dos papéis de IAM predefinidos, como o Editor da API Cloud Translation (roles/cloudtranslate.editor) ou crie um papel personalizado que conceda as permissões necessárias. É possível visualizar todas as permissões da API Cloud Translation na referência de permissões do IAM. As permissões de tradução começam com cloudtranslate.

Para criar glossários, você também precisa de permissões para ler objetos no bucket do Cloud Storage em que seu arquivo de glossário está localizado. É possível conceder um papel à sua conta de serviço usando um dos papéis de IAM predefinidos, como o Leitor de objetos do Storage (roles/storage.objectViewer), ou pode criar um papel personalizado que concede permissões para ler objetos.

Saiba mais sobre como adicionar uma conta a um papel em Como conceder, alterar e revogar o acesso a recursos.

Criar um glossário

Os termos em um glossário podem ser tokens únicos (palavras) ou frases curtas (geralmente menos de cinco palavras). O limite atual para o número de glossários separados é de 1.000 por projeto.

Estas são as principais etapas para usar um glossário:

Criar um arquivo de glossário
Criar o recurso de glossário com a API Cloud Translation
Especificar qual glossário usar ao solicitar uma tradução

Um projeto pode ter vários glossários. É possível conseguir uma lista dos glossários disponíveis e excluir aqueles que não são mais necessários.

Como criar um arquivo de glossário

Basicamente, um glossário é um arquivo de texto em que cada linha contém termos correspondentes em vários idiomas. A API Cloud Translation é compatível com glossários unidirecionais (que especificam a tradução que você quer para um único par de idiomas de origem e de chegada) e com conjuntos de termos equivalentes (que identificam os termos equivalentes em vários idiomas).

O número total de termos em um arquivo de entrada de glossário não pode exceder 10,4 milhões (10.485.760) de bytes UTF-8 em todos os termos de todos os idiomas combinados. Qualquer termo do glossário precisa ter menos de 1.024 bytes UTF-8. Os termos com mais do que isso serão ignorados.

Glossários unidirecionais

A API Cloud Translation aceita arquivos TSV, CSV ou TMX.

Valores separados por tabulação (TSV)

A API Cloud Translation é compatível com arquivos separados por tabulação, em que cada linha tem este formato:

Term in source language tabulação Term in target language

Por exemplo:

account\tcuenta
directions\tindicaciones

Os dados de origem separados por tabulação não incluem códigos de idioma para identificar os idiomas de origem e de chegada. Identifique os códigos de idioma de origem e de chegada ao criar o glossário.

Valores separados por vírgula (CSV)

Para cada linha em um arquivo CSV, use uma vírgula (,) para separar os termos do idioma de origem e de destino, conforme mostrado no exemplo a seguir:

account,cuenta
directions,indicaciones

Não inclua uma linha de cabeçalho no arquivo CSV para identificar os idiomas de origem e de chegada. Você os identifica quando cria o glossário.

Translation Memory eXchange (TMX)

O Translation Memory eXchange (TMX) é um formato XML padrão para fornecer traduções de origem e de destino. A API Cloud Translation é compatível com arquivos de entrada em um formato baseado na versão 1.4 do TMX. Veja neste exemplo a estrutura necessária:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE tmx SYSTEM "tmx14.dtd">
<tmx version="1.4">
  <header segtype="sentence" o-tmf="UTF-8"
  adminlang="en" srclang="en" datatype="PlainText"/>
  <body>
    <tu>
      <tuv xml:lang="en">
        <seg>account</seg>
      </tuv>
      <tuv xml:lang="es">
        <seg>cuenta</seg>
      </tuv>
    </tu>
    <tu>
      <tuv xml:lang="en">
        <seg>directions</seg>
      </tuv>
      <tuv xml:lang="es">
        <seg>indicaciones</seg>
      </tuv>
    </tu>
  </body>
</tmx>

O elemento <header> de um arquivo TMX bem formado precisa identificar o idioma de origem usando o atributo srclang, e cada elemento <tuv> precisa identificar o idioma do texto contido usando o atributo xml:lang. Use os códigos ISO-639-1 para identificar os idiomas de origem e de destino.

Todos os elementos <tu> precisam conter um par de elementos <tuv> com os mesmos idiomas de origem e de destino. Se um elemento <tu> contiver mais de dois elementos <tuv>, a API Cloud Translation processará apenas o primeiro <tuv> correspondente ao idioma de origem e o primeiro correspondente ao idioma de destino, ignorando o restante. Se um elemento <tu> não tiver um par correspondente de <tuv>, a API Cloud Translation ignorará o elemento <tu> inválido.

A API Cloud Translation remove as tags de marcação do entorno de um elemento <seg> antes de processá-lo. Se um elemento <tuv> contiver mais de um elemento <seg>, a API Cloud Translation concatenará o texto em um único elemento com um espaço entre eles.

Se o arquivo contiver tags XML diferentes das mostradas acima, a API Cloud Translation as ignorará.

Se o arquivo não estiver em conformidade com o formato XML e TMX adequado (por exemplo, se estiver faltando uma tag final ou um elemento <tmx>), a API Cloud Translation cancelará o processamento. A API Cloud Translation também cancela o processamento se ignorar mais de 1.024 elementos <tu> inválidos.

Conjuntos de termos equivalentes (CSV)

Para conjuntos de termos equivalentes, a API Cloud Translation aceita apenas arquivos no formato CSV. Para definir conjuntos de termos equivalentes, crie um arquivo CSV de várias colunas em que cada linha liste um único termo do glossário em vários idiomas.

A primeira linha do arquivo é um cabeçalho que identifica o idioma de cada coluna, usando o código de idioma ISO-639-1 ou BCP-47. Também é possível incluir colunas opcionais para a classe gramatical (pos, na sigla em inglês) e uma descrição (description).

Cada linha posterior contém termos de glossário equivalentes nos idiomas identificados no cabeçalho. Deixe as colunas em branco se o termo não estiver disponível em todos os idiomas.

Termos equivalentes definidos

Criar um recurso de glossário

Depois de identificar os termos de glossário equivalentes, disponibilize o arquivo de glossário para a API Cloud Translation criando um recurso de glossário.

Glossário unidirecional

Ao criar um glossário unidirecional, é preciso indicar o par de idiomas (language_pair) especificando os idiomas de origem (source_language_code) e de chegada (target_language_code). O exemplo a seguir usa a API REST e a linha de comando, mas também é possível usar as bibliotecas de cliente para criar um glossário unidirecional.

REST e LINHA DE CMD

Ao criar um novo glossário, você fornece um ID de glossário ou nome de recurso. Por exemplo:

projects/my-project/locations/us-central1/glossaries/my-en-to-ru-glossary

em que my-project é o project-number-or-id, e my-en-ru-glossary é o glossary-id fornecido por você.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

project-number-or-id: pelo número ou código do seu projeto do Google Cloud
glossary-id: pelo código de glossário, por exemplo, my_en_ru_glossary
bucket-name: o nome do bucket em que seu arquivo de glossário está localizado
glossary-filename: nome de arquivo do seu glossário

Método HTTP e URL:

POST https://translation.googleapis.com/v3/projects/project-number-or-id/locations/us-central1/glossaries

Corpo JSON da solicitação:

{
  "name":"projects/project-number-or-id/locations/us-central1/glossaries/glossary-id",
  "languagePair": {
    "sourceLanguageCode": "en",
    "targetLanguageCode": "ru"
    },
  "inputConfig": {
    "gcsSource": {
      "inputUri": "gs://bucket-name/glossary-filename"
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://translation.googleapis.com/v3/projects/project-number-or-id/locations/us-central1/glossaries

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://translation.googleapis.com/v3/projects/project-number-or-id/locations/us-central1/glossaries
" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/project-number/locations/us-central1/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.translation.v3beta1.CreateGlossaryMetadata",
    "name": "projects/project-number/locations/us-central1/glossaries/glossary-id",
    "state": "RUNNING",
    "submitTime": "2019-11-19T19:05:10.650047636Z"
  }
}

Glossário de conjuntos de termos equivalentes

Depois de identificar os termos de glossário equivalentes, disponibilize o arquivo de glossário para a API Cloud Translation criando um recurso de glossário.

REST e LINHA DE CMD

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

project-number-or-id: pelo número ou código do seu projeto do Google Cloud
glossary-id: seu código de glossário
bucket-name: o nome do bucket em que seu arquivo de glossário está localizado
glossary-filename: nome de arquivo do seu glossário

Método HTTP e URL:

POST https://translation.googleapis.com/v3/projects/project-number-or-id/locations/us-central1/glossaries

Corpo JSON da solicitação:

{
  "name":"projects/project-number-or-id/locations/us-central1/glossaries/glossary-id",
  "languageCodesSet": {
    "languageCodes": ["en", "en-GB", "ru", "fr", "pt-BR", "pt-PT", "es"]
  },
  "inputConfig": {
    "gcsSource": {
"inputUri": "gs://bucket-name/glossary-file-name"
    }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://translation.googleapis.com/v3/projects/project-number-or-id/locations/us-central1/glossaries

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json e execute o comando a seguir:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://translation.googleapis.com/v3/projects/project-number-or-id/locations/us-central1/glossaries
" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/project-number/locations/us-central1/operations/20191103-09061569945989-5d937985-0000-21ac-816d-f4f5e80782d4",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.translation.v3beta1.CreateGlossaryMetadata",
    "name": "projects/project-number/locations/us-central1/glossaries/glossary-id",
    "state": "RUNNING",
    "submitTime": "2019-11-03T16:06:29.134496675Z"
  }
}

C#

Antes de testar esta amostra, siga as instruções de configuração para C# no Guia de início rápido do Translation: como usar bibliotecas de cliente. Saiba mais na documentação de referência da API Translation para C#.

Como criar e usar glossários (Advanced)

Antes de começar

Permissões necessárias

Criar um glossário

Como criar um arquivo de glossário

Glossários unidirecionais

Valores separados por tabulação (TSV)

Valores separados por vírgula (CSV)

Translation Memory eXchange (TMX)

Conjuntos de termos equivalentes (CSV)

Criar um recurso de glossário

Glossário unidirecional

REST e LINHA DE CMD

curl

PowerShell

Glossário de conjuntos de termos equivalentes

REST e LINHA DE CMD

curl

PowerShell

C#

Go

Java

Node.js

PHP

Python

Ruby

Status da operação

Usar glossários

Traduzir texto com um glossário

REST e linha de comando

curl

PowerShell

C#

Go

Java

Node.js

PHP

Python

Ruby

Ver informações sobre um glossário

REST e linha de comando

curl

PowerShell

C#

Go

Java

Node.js

PHP

Python

Ruby

Listar glossários

REST e linha de comando

curl

PowerShell

C#

Go

Java

Node.js

PHP

Python

Ruby

Excluir um glossário

REST e linha de comando

curl

PowerShell

C#

Go

Java

Node.js

PHP

Python

Ruby