Introdução à tradução síncrona

  • Artigo

A tradução de documentos é um recurso de tradução automática baseado em nuvem do serviço Tradutor de IA do Azure. Você pode traduzir vários e complexos documentos em todos os idiomas e dialetos compatíveis, preservando a estrutura original do documento e o formato de dados.

A tradução síncrona dá suporte ao processamento de resposta imediata de arquivos de página única. O processo de tradução síncrona não requer uma conta de armazenamento de Blobs do Azure. A resposta final contém o documento traduzido e é retornada diretamente ao cliente que está fazendo a chamada.

Vamos começar.

Pré-requisitos

Você precisa de uma assinatura ativa do Azure. Se você não tem uma assinatura do Azure, pode criar uma gratuita.

  • Depois de obter sua assinatura do Azure, crie um recurso de Tradução no portal do Azure.

    Observação

    • Para este início rápido, recomendamos que você use um recurso global de serviço único de tradução de texto, a menos que sua empresa ou aplicativo exija uma região específica. Se você estiver planejando usar uma identidade gerenciada atribuída pelo sistema para autenticação, escolha uma região geográfica como Oeste dos EUA.
    • Com o recurso global de serviço único, você incluirá um cabeçalho de autorização (Ocp-Apim-Subscription-key) com a solicitação da API REST. O valor de Ocp-Apim-Subscription-key é a chave secreta do Azure para sua assinatura da Tradução de Texto.

  • Após a implantação do recurso, selecione Ir para o recurso para recuperar a chave e o ponto de extremidade.

    • Você precisará da chave e do ponto de extremidade do recurso para conectar seu aplicativo ao serviço de Tradução. Você vai colar a chave e o ponto de extremidade no código mais adiante no guia de início rápido. Você pode encontrar esses valores na página Chaves e ponto de extremidade do portal do Azure.

      Screenshot to document translation key and endpoint location in the Azure portal.

  • Para este projeto, usamos a ferramenta de linha de comando cURL para fazer chamadas à API REST.

    Observação

    O pacote cURL é pré-instalado na maioria dos Windows 10 e Windows 11 e na maioria das distribuições macOS e Linux. Você pode verificar a versão do pacote com os seguintes comandos: Windows: curl.exe -V macOS curl -V Linux: curl --version

  • Se o cURL não estiver instalado, aqui estão os links de instalação para sua plataforma:

Cabeçalhos e parâmetros

Para chamar o recurso de tradução síncrona por meio da API REST, você precisa incluir os seguintes cabeçalhos em cada solicitação. Não se preocupe, incluímos os cabeçalhos para você no código de exemplo.

Observação

Todos os sinalizadores cURL e opções de linha de comando diferenciam maiúsculas de minúsculas.

Parâmetro de consulta Descrição Condição
-X ou --requestPOST O sinalizador -X especifica o método de solicitação para acessar a API. Obrigatório
{endpoint} A URL do ponto de extremidade do recurso de tradução de documentos Obrigatório
targetLanguage Especifica o idioma do documento de saída. O idioma de destino deve ser um dos idiomas com suporte incluídos no escopo da tradução. Obrigatório
sourceLanguage Especifica o idioma do documento de entrada. Se o parâmetro sourceLanguage não for especificado, a detecção automática de idioma será aplicada para determinar o idioma de origem. Opcional
-H ou --header"Ocp-Apim-Subscription-Key:{KEY} Cabeçalho de solicitação que especifica a chave do recurso de tradução de documento que autoriza o acesso à API. Obrigatório
-F ou --form O caminho de arquivo para o documento que você deseja incluir com sua solicitação. Apenas um documento de origem é permitido. Obrigatório
• document=
• type={contentType}/fileExtension		 • Caminho para o local do arquivo para seu documento de origem.
• Tipo de conteúdo e extensão de arquivo.

Ex: "document=@C:\Test\test-file.md;type=text/markdown		 Obrigatório
-o ou --output O caminho de arquivo para os resultados da resposta. Obrigatório
-F ou --form O caminho de arquivo para um glossário opcional a ser incluído com sua solicitação. O glossário requer um sinalizador --form separado. Opcional
• glossary=
• type={contentType}/fileExtension		 • Caminho para o local do arquivo para seu arquivo de glossário opcional.
• Tipo de conteúdo e extensão de arquivo.

Ex: "glossary=@C:\Test\glossary-file.txt;type=text/plain		 Opcional

✔️ Para obter mais informações sobre contentType, consulteFormatos de documentos compatíveis.

Compilar e executar a solicitação POST

  1. Para este projeto, você precisa de um documento de exemplo. Você pode baixar nosso Documento de exemplo do Microsoft Word para este início rápido. O idioma de origem é o inglês.

  2. Antes de executar a solicitação POST, substitua {your-document-translation-endpoint} e {your-key} pelos valores de sua instância de serviço Tradutor do portal do Azure.

    Importante

    Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Para obter mais informações, consulte a segurança dos serviços de IA do Azure.

    Terminal/prompt de comando

    
curl -i -X POST "{your-document-translation-endpoint}/translator/document:translate?sourceLanguage=en&targetLanguage=hi&api-version=2023-11-01-preview" -H "Ocp-Apim-Subscription-Key:{your-key}"  -F "document={path-to-your-document-with-file-extension};type={ContentType}/{file-extension}" -F "glossary={path-to-your-glossary-with-file-extension};type={ContentType}/{file-extension}" -o "{path-to-output-file}"

    PowerShell

    cmd /c curl "{your-document-translation-endpoint}/translator/document:translate?sourceLanguage=en&targetLanguage=es&api-version=2023-11-01-preview" -i -X POST  -H "Ocp-Apim-Subscription-Key: {your-key}" -F "{path-to-your-document-with-file-extension};type=text/{file-extension}" -o "{path-to-output-file}

    ✔️ Para obter mais informações sobre Query parameters, consulteCabeçalhos e parâmetros.

Após a conclusão bem-sucedida:

  • O documento traduzido é retornado com a resposta.
  • O método POST bem-sucedido retorna um código de resposta 200 OK indicando que o serviço criou a solicitação.

É isso, parabéns! Você acabou de aprender a traduzir um documento de forma síncrona usando o serviço Tradutor de IA do Azure.

Próximas etapas

Tradução assíncrona em lote