Criar e usar glossários (avançado)

Um glossário é um dicionário personalizado que a Cloud Translation API usa para traduzir de forma consistente a terminologia específica do domínio do cliente. Normalmente, isto envolve especificar como traduzir uma entidade com nome.

Pode usar um glossário para os seguintes exemplos de utilização:

• Nomes de produtos: por exemplo, "Google Home" tem de ser traduzido para "Google Home".
• Palavras ambíguas: por exemplo, a palavra "morcego" pode significar um animal ou um objeto usado para jogar basebol. Se souber que está a traduzir palavras sobre desporto, pode querer usar um glossário para fornecer à API Cloud Translation a tradução de "bat" no contexto de desporto e não a tradução para o animal.
• Palavras emprestadas: por exemplo, "bouillabaisse" em francês é traduzido como "bouillabaisse" em inglês. O inglês tomou emprestada a palavra "bouillabaisse" do francês no século XIX. Um falante de inglês sem contexto cultural francês pode não saber que a bouillabaisse é um prato de caldeirada de peixe. Os glossários podem substituir uma tradução para que "bouillabaisse" em francês seja traduzido como "caldeirada de peixe" em inglês.

Antes de começar

Antes de poder começar a usar a API Cloud Translation, tem de ter um projeto com a API Cloud Translation ativada e as credenciais adequadas. Também pode instalar bibliotecas cliente para linguagens de programação comuns para ajudar a fazer chamadas para a API. Para mais informações, consulte a página Configuração.

Autorizações necessárias

Para trabalhar com glossários, a sua conta de serviço requer autorizações específicas do glossário. Pode conceder uma função à sua conta de serviço através de uma das funções do IAM predefinidas, como Editor da API Cloud Translation (roles/cloudtranslate.editor), ou pode criar uma função personalizada que conceda as autorizações necessárias. Pode ver todas as autorizações da API Cloud Translation na referência de autorizações de IAM. As autorizações da Tradução Cloud começam com cloudtranslate.

Para criar glossários, também precisa de autorizações para ler objetos no contentor do Cloud Storage onde se encontra o ficheiro do glossário. Pode conceder uma função à sua conta de serviço através de uma das funções de IAM predefinidas, como Leitor de objetos do Storage (roles/storage.objectViewer), ou pode criar uma função personalizada que conceda autorizações para ler objetos.

Para informações sobre como adicionar uma conta a uma função, consulte o artigo Conceder, alterar e revogar o acesso a recursos.

Crie um glossário

Os termos num glossário podem ser tokens únicos (palavras) ou expressões curtas (normalmente, com menos de cinco palavras). Os principais passos para usar um glossário são:

1. Crie um ficheiro de glossário
2. Crie o recurso de glossário com a nossa Cloud Translation API
3. Especifique que glossário usar quando pedir uma tradução

Um projeto pode ter vários glossários. Pode aceder a uma lista dos glossários disponíveis e eliminar glossários de que já não precisa.

Palavras ignoradas

O Cloud Translation ignora alguns termos incluídos num glossário. Estes termos são conhecidos como palavras vazias. Quando traduz palavras vazias, o Cloud Translation ignora todas as entradas do glossário correspondentes. Para ver uma lista de todas as palavras irrelevantes, consulte o artigo Palavras irrelevantes do glossário.

Criar um ficheiro de glossário

Fundamentalmente, um glossário é um ficheiro de texto em que cada linha contém termos correspondentes em vários idiomas. A Cloud Translation API suporta glossários unidirecionais, que especificam a tradução pretendida para um único par de idiomas de origem e destino, e conjuntos de termos equivalentes, que identificam os termos equivalentes em vários idiomas.

O número total de termos num ficheiro de entrada do glossário não pode exceder 10,4 milhões (10 485 760) de bytes UTF-8 para todos os termos em todos os idiomas combinados. Qualquer termo do glossário tem de ter menos de 1024 bytes UTF-8. Os termos com mais de 1024 bytes são ignorados.

Por predefinição, as correspondências do glossário são sensíveis a maiúsculas e minúsculas. Quando aplica um glossário, pode ignorar as maiúsculas e minúsculas para todas as entradas. Se tiver uma combinação de termos sensíveis a maiúsculas e minúsculas e termos não sensíveis a maiúsculas e minúsculas, use o comportamento predefinido e, para termos não sensíveis a maiúsculas e minúsculas, inclua ambas as formas no glossário.

Glossários unidirecionais

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

TSV e CSV

Para valores separados por tabulações (TSV) e valores separados por vírgulas (CSV), cada linha contém um par de termos separados por uma tabulação (\t) ou uma vírgula (,). A primeira coluna inclui o termo no idioma de origem e a segunda coluna inclui o termo no idioma de destino, conforme mostrado no exemplo seguinte:

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 suporta ficheiros de entrada num formato baseado na versão 1.4 do TMX. Este exemplo ilustra 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 ficheiro TMX bem formado tem de identificar o idioma de origem através do atributo srclang, e cada elemento <tuv> tem de identificar o idioma do texto contido através do atributo xml:lang. Identifica os idiomas de origem e destino através dos respetivos códigos ISO-639.

Todos os elementos <tu> têm de 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 Cloud Translation API processa apenas o primeiro elemento <tuv> que corresponda ao idioma de origem e o primeiro que corresponda ao idioma de destino, ignorando os restantes. Se um elemento <tu> não tiver um par correspondente de elementos <tuv>, a API Cloud Translation ignora o elemento <tu> inválido.

A Cloud Translation API remove as etiquetas de marcação de um elemento <seg> antes de o processar. Se um elemento <tuv> contiver mais do que um elemento <seg>, a API Cloud Translation concatena o respetivo texto num único elemento com um espaço entre eles.

Se o ficheiro contiver etiquetas XML diferentes das apresentadas acima, a API Cloud Translation ignora-as.

Se o ficheiro não estiver em conformidade com o formato XML e TMX adequado, por exemplo, se lhe faltar uma etiqueta final ou um elemento <tmx>, a Cloud Translation API interrompe o respetivo processamento. A API Cloud Translation também interrompe o processamento se ignorar mais de 1024 elementos <tu> inválidos.

Conjuntos de termos equivalentes (CSV)

Para conjuntos de termos equivalentes, a API Cloud Translation só aceita ficheiros no formato CSV. Para definir conjuntos de termos equivalentes, crie um ficheiro CSV com várias colunas em que cada linha apresenta um único termo do glossário em vários idiomas.

A primeira linha do ficheiro é uma linha de cabeçalho que identifica o idioma de cada coluna, através do respetivo código de idioma ISO-639 ou BCP-47. Também pode incluir colunas opcionais para a parte do discurso (pos) e uma descrição (description). Atualmente, o algoritmo não usa informações de pos e os valores de pos específicos não são validados.

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

Crie um recurso de glossário

Depois de identificar os termos do glossário equivalentes, disponibilize o ficheiro do glossário à API Cloud Translation criando um recurso de glossário.

Glossário unidirecional

Quando cria um glossário unidirecional, tem de indicar o par de idiomas (language_pair) especificando o idioma de origem (source_language_code) e o idioma de destino (target_language_code). O exemplo seguinte usa a API REST e a linha de comandos, mas também pode usar as bibliotecas de cliente para criar um glossário unidirecional.

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

POST https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID/locations/us-central1/glossaries

{
  "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"
    }
  }
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_NUMBER_OR_ID" \
     -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"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER_OR_ID" }

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

{
  "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 do glossário no conjunto de termos equivalente, disponibilize o ficheiro do glossário à API Cloud Translation criando um recurso do glossário.

POST https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID/locations/us-central1/glossaries

{
  "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"
    }
  }
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_NUMBER_OR_ID" \
     -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"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER_OR_ID" }

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

{
  "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"
  }
}

import (
	"context"
	"fmt"
	"io"

	translate "cloud.google.com/go/translate/apiv3"
	"cloud.google.com/go/translate/apiv3/translatepb"
)

// createGlossary creates a glossary to use for other operations.
func createGlossary(w io.Writer, projectID string, location string, glossaryID string, glossaryInputURI string) error {
	// projectID := "my-project-id"
	// location := "us-central1"
	// glossaryID := "my-glossary-display-name"
	// glossaryInputURI := "gs://cloud-samples-data/translation/glossary.csv"

	ctx := context.Background()
	client, err := translate.NewTranslationClient(ctx)
	if err != nil {
		return fmt.Errorf("NewTranslationClient: %w", err)
	}
	defer client.Close()

	req := &translatepb.CreateGlossaryRequest{
		Parent: fmt.Sprintf("projects/%s/locations/%s", projectID, location),
		Glossary: &translatepb.Glossary{
			Name: fmt.Sprintf("projects/%s/locations/%s/glossaries/%s", projectID, location, glossaryID),
			Languages: &translatepb.Glossary_LanguageCodesSet_{
				LanguageCodesSet: &translatepb.Glossary_LanguageCodesSet{
					LanguageCodes: []string{"en", "ja"},
				},
			},
			InputConfig: &translatepb.GlossaryInputConfig{
				Source: &translatepb.GlossaryInputConfig_GcsSource{
					GcsSource: &translatepb.GcsSource{
						InputUri: glossaryInputURI,
					},
				},
			},
		},
	}

	// The CreateGlossary operation is async.
	op, err := client.CreateGlossary(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateGlossary: %w", err)
	}
	fmt.Fprintf(w, "Processing operation name: %q\n", op.Name())

	resp, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("Wait: %w", err)
	}

	fmt.Fprintf(w, "Created: %v\n", resp.GetName())
	fmt.Fprintf(w, "Input URI: %v\n", resp.InputConfig.GetGcsSource().GetInputUri())

	return nil
}

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.translate.v3.CreateGlossaryMetadata;
import com.google.cloud.translate.v3.CreateGlossaryRequest;
import com.google.cloud.translate.v3.GcsSource;
import com.google.cloud.translate.v3.Glossary;
import com.google.cloud.translate.v3.GlossaryInputConfig;
import com.google.cloud.translate.v3.GlossaryName;
import com.google.cloud.translate.v3.LocationName;
import com.google.cloud.translate.v3.TranslationServiceClient;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;

public class CreateGlossary {

  public static void createGlossary() throws InterruptedException, ExecutionException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "YOUR-PROJECT-ID";
    String glossaryId = "your-glossary-display-name";
    List<String> languageCodes