PTC
Cadastrar-se Fazer upgrade para o Pro Sua conta

Como traduzir conteúdo dinâmico no Rails usando a API da PTC

Aprenda a usar a API da PTC para traduzir conteúdo dinâmico na sua aplicação Ruby on Rails (RoR). Isso inclui posts de blog, informações de produtos e qualquer texto armazenado no seu banco de dados.

Abaixo, guiaremos você pelo processo de tradução de conteúdo dinâmico em aplicações Rails em duas partes:

  • Primeiro, você aprenderá sobre os três endpoints da API individualmente — como enviar conteúdo para tradução, verificar seu status e recuperar traduções concluídas.
  • Depois, você verá como conectar esses endpoints em um fluxo de trabalho completo usando callbacks ou consultas periódicas.

Antes de começar

Este guia pressupõe que você tem uma aplicação Rails configurada com uma forma de armazenar traduções (como a gem Mobility, a gem Globalize ou sua própria solução).

Se você estiver começando do zero ou quiser ver uma implementação completa, criamos uma aplicação Rails de demonstração que mostra a integração com a PTC de ponta a ponta. A demonstração usa:

Configure a PTC e obtenha seu token de API

Para começar, você precisa de uma conta na PTC e de um token de API:

  1. Inscreva-se na PTC. Criar uma conta leva um minuto, e o teste cobre 20.000 palavras em 2 idiomas. Depois, você paga pelo que traduzir.
  2. Crie um novo projeto e selecione Integração via API.
  3. Copie o token de API que a PTC gera no final da configuração do projeto. Você precisará deste token para autenticar todas as solicitações. Você pode encontrar o mesmo token no painel do seu projeto em Configurações → Gerenciar tokens de API.
Criando um novo projeto na PTC
Criando um novo projeto
Escolhendo a integração via API na configuração da PTC
Escolhendo a integração via API
Token de API em Configurações → Gerenciar tokens de API
Token de API em Configurações → Gerenciar tokens de API

Endpoints da API para traduzir conteúdo dinâmico

Enviar conteúdo para tradução

Para traduzir conteúdo, use o endpoint Create Content Translation. Isso agenda seu conteúdo para tradução e retorna um ID que você usará para acompanhar o progresso e recuperar os resultados.

Endpoint:

POST https://app.ptc.wpml.org/api/v1/content_translation

Parâmetros:

  • data (obrigatório) – O conteúdo a ser traduzido como um hash
  • name (obrigatório) – Um rótulo para esta tarefa de tradução (por exemplo, "post-123-translation")
  • target_languages (opcional) – Um array de códigos de idioma (por exemplo, ["es", "fr", "de"])
  • callback_url (opcional) – Uma URL onde a PTC notificará você assim que as traduções estiverem prontas

Aqui está um exemplo de serviço que inicia a tradução:

Ruby

require 'net/http'
require 'uri'

module Ptc
  class TranslateService
    def initialize(data:, name:, target_languages:, callback_url: nil)
      @data = data
      @name = name
      @target_languages = target_languages
      @token = ENV.fetch("PTC_API_TOKEN")
      @callback_url = callback_url
    end

    def call
      translate
    end

    def self.call(**attributes)
      new(**attributes).call
    end

    private
    attr_reader :data, :name, :target_languages, :token, :callback_url

    def translate
      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
        http.request(request)
      end
      JSON.parse(response.body)
    end

    def body
      {
        data:,
        name:,
        target_languages:,
        callback_url:,
      }.to_json
    end

    def request
      return @request if @request.present?

      @request ||= Net::HTTP::Post.new(uri)
      @request.content_type = "application/json"
      @request.body = body
      @request["Authorization"] = "Bearer #{token}"
      @request
    end

    def uri
      @uri ||= URI.parse("https://app.ptc.wpml.org/api/v1/content_translation")
    end
  end
end

Para detalhes completos da resposta, códigos de erro e exemplos adicionais, consulte a documentação da API Create Content Translation.

Verificar o status da tradução

Para verificar se sua tradução está concluída, use o endpoint Get Content Translation Status. Ele retorna o status atual e o progresso da tradução.

Endpoint:

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/status

Parâmetros:

  • id (obrigatório) – O identificador único da tarefa de tradução de conteúdo a ser verificada

Exemplo de serviço no Rails:

Ruby

require 'net/http'
require 'uri'

module Ptc
  class GetTranslationStatusService
    def initialize(id:)
      @id = id
      @token = ENV.fetch("PTC_API_TOKEN")
    end

    def call
      get
    end

    def self.call(**attributes)
      new(**attributes).call
    end

    private
    attr_reader :id, :token

    def get
      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
        http.request(request)
      end
      JSON.parse(response.body)
    end

    def request
      return @request if @request.present?

      @request ||= Net::HTTP::Get.new(uri)
      @request.content_type = "application/json"
      @request["Authorization"] = "Bearer #{token}"
      @request
    end

    def uri
      @uri ||= URI.parse("https://app.ptc.wpml.org/api/v1/content_translation/#{id}/status")
    end
  end
end

A resposta inclui um campo de status e uma porcentagem mostrando o progresso da tradução. Para detalhes completos da resposta, consulte a documentação da API Get Content Translation.

Recuperar traduções

Quando sua tradução estiver concluída, use o endpoint Get Content Translations para buscar os resultados. Ele retorna seu conteúdo original mais as versões traduzidas para cada idioma de destino.

Endpoint:

GET https://app.ptc.wpml.org/api/v1/content_translation/{id}

Parâmetros:

  • id (obrigatório) – O identificador único da tarefa de tradução de conteúdo a ser recuperada

Exemplo no Rails:

Ruby

require 'net/http'
require 'uri'

module Ptc
  class GetTranslationService
    def initialize(id:)
      @id = id
      @token = ENV.fetch("PTC_API_TOKEN")
    end

    def call
      get
    end

    def self.call(**attributes)
      new(**attributes).call
    end

    private
    attr_reader :id, :token

    def get
      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
        http.request(request)
      end
        JSON.parse(response.body)
    end

    def request
      return @request if @request.present?

      @request ||= Net::HTTP::Get.new(uri)
      @request.content_type = "application/json"
      @request["Authorization"] = "Bearer #{token}"
      @request
    end

    def uri
      @uri ||= URI.parse("https://app.ptc.wpml.org/api/v1/content_translation/#{id}")
    end
  end
end

Seja notificado quando as traduções estiverem prontas

Você aprendeu como enviar conteúdo, verificar o status e recuperar traduções. Agora você precisa conectar essas etapas para que sua aplicação saiba automaticamente quando buscar as traduções.

Você pode fazer isso usando callbacks (recomendado) ou executando uma tarefa que faz consultas periódicas do status da tradução.

Usando callbacks (recomendado)

Quando você envia conteúdo para tradução, pode incluir uma URL de callback. A PTC chama essa URL quando a tradução é concluída. Seu endpoint então busca e armazena as traduções.

Isso é eficiente porque a PTC notifica você imediatamente.

Ruby

module Api
  class CallbacksController < ActionController::API
    before_action :set_post

    def create
      id = callback_params[:id]

      translation_data = Ptc::GetTranslationService.call(id:)
      translation_data.except("source").each do |locale, data|
        @post.set_translation(locale:, title: data["title"], description: data["description"])
      end

      head :ok
    end

    private

    def set_post
      @post = Post.find(params[:post_id])
    end

    def callback_params
      params.permit([:post_id, :id, :status, :translations_url])
    end
  end
end

Consultas periódicas do status da tradução (alternativa)

Não pode usar callbacks? Depois de enviar o conteúdo para tradução, você pode colocar na fila uma tarefa em segundo plano que verifica repetidamente o status da tradução. A tarefa busca as traduções quando concluídas.

Essa abordagem não é recomendada porque desperdiça recursos e adiciona chamadas de API desnecessárias.

Ruby

class CheckTranslationJob < ApplicationJob

  MAX_ATTEMPTS = 3

  def perform(id:, post_id:, attempt: 0)
    translation = Ptc::GetTranslationStatusService.call(id:)
    if translation["status"] == "completed"
      translation = Ptc::GetTranslationService.call(id:)
      post = Post.find(post_id)
      translation.except("source").each do |locale, data|
        post.set_translation(locale:, title: data["title"], description: data["description"])
      end
    else
      raise "Failed to get translation after #{MAX_ATTEMPTS} attempts" if attempt > MAX_ATTEMPTS

      CheckTranslationJob.set(wait: 1.minute).perform_later(id:, post_id:, attempt: attempt + 1)
    end
  end
end

Comece a traduzir sua aplicação Rails

Agora você tem tudo o que precisa para integrar a API de tradução da PTC. Crie uma conta e traduza 20.000 palavras para 2 idiomas durante o teste.

Nesta página

Antes de começar

Configure a PTC e obtenha seu token de API

Endpoints da API para traduzir conteúdo dinâmico

Enviar conteúdo para tradução

Verificar o status da tradução

Recuperar traduções

Seja notificado quando as traduções estiverem prontas

Usando callbacks (recomendado)

Consultas periódicas do status da tradução (alternativa)

Pronto para começar a usar a PTC? Inscreva-se para um teste de 30 dias.