Criar e usar um glossário

Você pode usar um glossário para definir a terminologia específica do seu domínio. Com um glossário, é possível adicionar pares de termos, incluindo um termo de origem e um de destino. Os pares de termos garantem que o serviço de tradução da Vertex AI traduza seu vocabulário de forma consistente.

Confira alguns exemplos de casos em que você pode definir entradas de glossário:

• Nomes de produtos: identifique os nomes de produtos para mantê-los na tradução. Por exemplo, Google Home precisa ser traduzido como Google Home.
• Palavras ambíguas: especifique o significado de palavras vagas e homônimos. Por exemplo, morcego pode significar um equipamento esportivo ou um animal.
• Palavras emprestadas: esclareça o significado de palavras adotadas de um idioma diferente. Por exemplo, bouillabaisse em francês é traduzido como bouillabaisse em inglês, um prato de ensopado de peixe.

Os termos em um glossário podem ser palavras únicas (também chamadas de tokens) ou frases curtas, geralmente com menos de cinco palavras. A Vertex AI Translation ignora as entradas correspondentes do glossário se as palavras forem palavras de parada.

A Vertex AI Translation oferece os seguintes métodos de glossário disponíveis no Google Distributed Cloud (GDC) com isolamento físico:

Antes de começar

Antes de criar um glossário para definir sua terminologia de tradução, você precisa ter um projeto chamado translation-glossary-project. O recurso personalizado do projeto precisa ser semelhante ao exemplo a seguir:

  apiVersion: resourcemanager.gdc.goog/v1
  kind: Project
  metadata:
    labels:
      atat.config.google.com/clin-number: CLIN_NUMBER
      atat.config.google.com/task-order-number: TASK_ORDER_NUMBER
    name: translation-glossary-project
    namespace: platform

Para receber as permissões necessárias para usar um glossário, peça ao administrador do IAM do projeto para conceder a você os seguintes papéis no namespace do projeto:

• Desenvolvedor de tradução de IA: receba a função Desenvolvedor de tradução de IA (ai-translation-developer) para acessar o serviço de tradução da Vertex AI.
• Administrador de buckets do projeto: receba o papel de administrador de buckets do projeto (project-bucket-admin) para gerenciar buckets de armazenamento e objetos dentro deles, o que permite criar e fazer upload de arquivos.

Para mais informações sobre pré-requisitos, consulte Configurar um projeto de tradução.

Criar um arquivo de glossário

Você precisa criar um arquivo de glossário para armazenar os termos nos idiomas de origem e de destino. Esta seção contém os dois layouts de glossário diferentes que você pode usar para definir seus termos.

A tabela a seguir descreve os limites aceitos no Distributed Cloud para arquivos de glossário:

Escolha um dos seguintes layouts para o arquivo de glossário:

• Glossário unidirecional: especifique a tradução esperada para um par de termos de origem e de destino em um idioma específico. Os glossários unidirecionais são compatíveis com os formatos de arquivo TSV, CSV e TMX.
• Glossário de conjuntos de termos equivalentes: especifique a tradução esperada em vários idiomas em cada linha. Os glossários de conjuntos de termos equivalentes são compatíveis com formatos de arquivo CSV.

Glossário unidirecional

A API Vertex AI Translation aceita valores separados por tabulação (TSV) e valores separados por vírgula (CSV). Cada linha contém um par de termos separados por uma tabulação (\t) ou uma vírgula (,) para esses formatos de arquivo.

A API Vertex AI Translation também aceita o formato Translation Memory eXchange (TMX), um formato XML padrão para fornecer pares de termos de origem e destino da tradução. Os arquivos de entrada aceitos estão em um formato baseado na versão 1.4 do TMX.

Os exemplos a seguir mostram a estrutura necessária para formatos de arquivo TSV, CSV e TMX de glossários unidirecionais:

<?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>

Depois de identificar os termos no glossário unidirecional, faça upload do arquivo para um bucket de armazenamento e disponibilize-o para a API Vertex AI Translation criando e importando um glossário.

Glossário de conjuntos de termos equivalentes

A API Vertex AI Translation aceita arquivos de glossário para conjuntos de termos equivalentes usando o formato CSV. Para definir conjuntos de termos equivalentes, crie um arquivo CSV de várias colunas em que cada linha lista um único termo do glossário em vários idiomas. Confira a lista de idiomas compatíveis e os respectivos códigos.

A imagem a seguir mostra um exemplo de arquivo CSV de várias colunas. Cada linha representa um termo do glossário, e cada coluna representa uma tradução do termo em diferentes idiomas.

O cabeçalho é a primeira linha do arquivo, que identifica o idioma de cada coluna. A linha de cabeçalho usa os códigos de idioma padrão ISO-639-1 ou BCP-47. A API Vertex AI Translation não usa informações de classe gramatical (pos), e valores de posição específicos não são validados.

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.

Depois de identificar os termos de glossário no conjunto de termos equivalentes, faça upload do arquivo para um bucket de armazenamento e disponibilize-o para a API Vertex AI Translation criando e importando um glossário.

Fazer upload do arquivo de glossário para um bucket de armazenamento

Siga estas etapas para fazer upload do arquivo de glossário em um bucket de armazenamento:

1. Configure a CLI gdcloud para armazenamento de objetos.

2. Crie um bucket de armazenamento no namespace do projeto. Use uma classe de armazenamento Standard.

   Para criar o bucket de armazenamento, implante um recurso Bucket no namespace do projeto:

     apiVersion: object.gdc.goog/v1
     kind: Bucket
     metadata:
       name: glossary-bucket
       namespace: translation-glossary-project
     spec:
       description: bucket for translation glossary
       storageClass: Standard
       bucketPolicy:
         lockingPolicy:
           defaultObjectRetentionDays: 90
   

3. Conceda permissões read no bucket à conta de serviço (ai-translation-system-sa) usada pelo serviço Vertex AI Translation.

   Siga estas etapas para criar a função e a vinculação de função usando recursos personalizados:

   1. Crie a função implantando um recurso Role no namespace do projeto:

        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: ai-translation-glossary-reader
          namespace: translation-glossary-project
        rules:
          -
            apiGroups:
              - object.gdc.goog
            resources:
              - buckets
            verbs:
              - read-object
      

   2. Implante um recurso RoleBinding no namespace do projeto para criar a vinculação de função:

        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: ai-translation-glossary-reader-rolebinding
          namespace: translation-glossary-project
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: ai-translation-glossary-reader
        subjects:
          -
            kind: ServiceAccount
            name: ai-translation-system-sa
            namespace: ai-translation-system
      

4. Faça upload do arquivo de glossário para o bucket de armazenamento que você criou. Para mais informações, consulte Fazer upload e download de objetos de armazenamento em projetos.

Criar um glossário

O método CreateGlossary cria um glossário e retorna o identificador para a operação de longa duração que gera o glossário.

Para criar um glossário, substitua o seguinte antes de usar os dados da solicitação:

• ENDPOINT: o endpoint da Vertex AI Translation que você usa na sua organização. Para mais informações, consulte o status e os endpoints do serviço.
• PROJECT_ID: o ID do projeto.
• GLOSSARY_ID: o ID do glossário, que é o nome do recurso.
• BUCKET_NAME: o nome do bucket de armazenamento em que o arquivo de glossário está localizado.
• GLOSSARY_FILENAME: o nome do arquivo de glossário no bucket de armazenamento.

Esta é a sintaxe de uma solicitação HTTP para criar um glossário:

POST https://ENDPOINT/v3/projects/PROJECT_ID/glossaries

De acordo com o arquivo de glossário que você criou, escolha uma das seguintes opções para criar um glossário:

curl -X POST \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://ENDPOINT/v3/projects/PROJECT_ID/glossaries"

$cred = TOKEN
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest
  -Method POST
  -Headers $headers
  -ContentType: "application/json; charset=utf-8"
  -InFile request.json
  -Uri "https://ENDPOINT/v3/projects/PROJECT_ID/glossaries"
  | Select-Object -Expand Content

{
"name": "projects/PROJECT_ID/operations/operation-id",
"metadata": {
    "@type": "type.googleapis.com/google.cloud.translation.v3.CreateGlossaryMetadata",
    "name": "projects/PROJECT_ID/glossaries/GLOSSARY_ID",
    "state": "RUNNING",
    "submitTime": TIME
  }
}

curl -X POST \
    -H "Authorization: Bearer TOKEN" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://ENDPOINT/v3/projects/PROJECT_ID/glossaries"

{
  "name": "projects/PROJECT_ID/operations/GLOSSARY_ID,
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.translation.v3.CreateGlossaryMetadata",
    "name": "projects/PROJECT_ID/glossaries/GLOSSARY_ID",
    "state": "RUNNING",
    "submitTime": TIME
  }
}

$cred = TOKEN
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://ENDPOINT/v3/projects/PROJECT_ID/glossaries"
  | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/operations/GLOSSARY_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.translation.v3.CreateGlossaryMetadata",
    "name": "projects/PROJECT_ID/glossaries/GLOSSARY_ID",
    "state": "RUNNING",
    "submitTime": TIME
  }
}

Dependendo do tamanho do arquivo, a criação de um glossário geralmente leva menos de 10 minutos. É possível recuperar o status dessa operação para saber quando ela será concluída.

Acessar um glossário

O método GetGlossary retorna um glossário armazenado. Se o glossário não existir, a saída vai retornar o valor NOT_FOUND. Para chamar o método GetGlossary, especifique o ID do projeto e do glossário. Os métodos CreateGlossary e ListGlossaries retornam o ID do glossário.

Por exemplo, as solicitações a seguir retornam informações sobre um glossário específico no seu projeto:

curl -X GET \
   -H "Authorization: Bearer TOKEN" \
   "http://ENDPOINT/v3/projects/PROJECT_ID/glossaries/GLOSSARY_ID"

from google.cloud import translate_v3 as translate

def get_glossary(project_id="PROJECT_ID", glossary_id="GLOSSARY_ID"):
    """Get a particular glossary based on the glossary ID."""

client = translate.TranslationServiceClient()

name = client.glossary_path(project_id, glossary_id)

response = client.get_glossary(name=name)
print(u"Glossary name: {}".format(response.name))
print(u"Input URI: {}".format(response.input_config.s3_source.input_uri))

Listar glossários

O método ListGlossaries retorna uma lista de IDs de glossário em um projeto. Se um glossário não existir, a saída vai retornar o valor NOT_FOUND. Para chamar o método ListGlossaries, especifique o ID do projeto e o endpoint da Vertex AI Translation.

Por exemplo, a solicitação a seguir retorna uma lista de IDs de glossário no seu projeto:

curl -X GET \
    -H "Authorization: Bearer TOKEN" \
    "http://ENDPOINT/v3/projects/PROJECT_ID/glossaries?page_size=10"

Substitua TOKEN pelo token de autenticação que você recebeu.

Excluir um glossário

O método DeleteGlossary exclui um glossário. Se o glossário não existir, a saída vai retornar o valor NOT_FOUND. Para chamar o método DeleteGlossary, especifique o ID do projeto, o ID do glossário e o endpoint da Vertex AI Translation. Os métodos CreateGlossary e ListGlossaries retornam o ID do glossário.

Por exemplo, a solicitação a seguir exclui um glossário do seu projeto:

curl -X DELETE \
    -H "Authorization: Bearer TOKEN" \
    "http://ENDPOINT/v3/projects/PROJECT_ID/glossaries/GLOSSARY_ID"

Substitua TOKEN pelo token de autenticação que você recebeu.