Come tradurre il contenuto dinamico in Rails usando l'API PTC

Scopri come usare l'API PTC per tradurre il contenuto dinamico nella tua applicazione Ruby on Rails (RoR). Questo include articoli del blog, informazioni sui prodotti e qualsiasi testo memorizzato nel tuo database.

Di seguito, ti guideremo attraverso il processo di traduzione del contenuto dinamico nelle applicazioni Rails in due parti:

• Per prima cosa, imparerai a conoscere i tre endpoint API singolarmente: come inviare i contenuti per la traduzione, controllarne lo stato e recuperare le traduzioni completate.
• Poi, vedrai come collegare questi endpoint in un flusso di lavoro completo usando i callback o il polling.

Prima di iniziare

Questa guida presuppone che tu abbia un'applicazione Rails configurata con un metodo per memorizzare le traduzioni (come Mobility, Globalize o una tua soluzione).

Se stai partendo da zero o vuoi vedere un'implementazione completa, abbiamo creato un'applicazione Rails dimostrativa che mostra l'integrazione di PTC dall'inizio alla fine. La demo usa:

• Mobility per memorizzare le traduzioni
• dotenv-rails per le variabili d'ambiente
• delayed_job_active_record per l'elaborazione in background

Configura PTC e ottieni il tuo token API

Per iniziare, hai bisogno di un account PTC e di un token API:

1. Iscriviti a PTC. Creare un account richiede un minuto e la prova copre 20.000 parole in 2 lingue. Successivamente, paghi per ciò che traduci.
2. Crea un nuovo progetto e seleziona API integration.
3. Copia il token API che PTC genera alla fine della configurazione del progetto. Avrai bisogno di questo token per autenticare tutte le richieste. Puoi trovare lo stesso token nel pannello di controllo del tuo progetto in Impostazioni → Gestisci token API.

Endpoint API per tradurre il contenuto dinamico

Inviare il contenuto per la traduzione

Per tradurre il contenuto, usa l'endpoint Create Content Translation. Questo programma la traduzione del tuo contenuto e restituisce un ID che userai per monitorare i progressi e recuperare i risultati.

Endpoint:

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

Parametri:

• data (obbligatorio) – Il contenuto da tradurre come hash
• name (obbligatorio) – Un'etichetta per questo job di traduzione (ad esempio, "post-123-translation")
• target_languages (opzionale) – Un array di codici lingua (ad esempio, ["es", "fr", "de"])
• callback_url (opzionale) – Un URL a cui PTC ti invierà una notifica una volta che le traduzioni saranno pronte

Ecco un servizio di esempio che avvia la traduzione:

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

Per i dettagli completi della risposta, i codici di errore e ulteriori esempi, consulta la documentazione dell'API Create Content Translation.

Controllare lo stato della traduzione

Per verificare se la tua traduzione è completa, usa l'endpoint Get Content Translation Status. Questo restituisce lo stato attuale e il progresso della traduzione.

Endpoint:

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

Parametri:

• id (obbligatorio) – L'identificatore univoco del job di traduzione del contenuto da controllare

Servizio di esempio in 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

La risposta include un campo di stato e una percentuale che mostra il progresso della traduzione. Per i dettagli completi della risposta, consulta la documentazione dell'API Get Content Translation.

Recuperare le traduzioni

Una volta completata la traduzione, usa l'endpoint Get Content Translations per recuperare i risultati. Questo restituisce il tuo contenuto originale più le versioni tradotte per ogni lingua di destinazione.

Endpoint:

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

Parametri:

• id (obbligatorio) – L'identificatore univoco del job di traduzione del contenuto da recuperare

Esempio in 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

Ricevere una notifica quando le traduzioni sono pronte

Hai imparato come inviare i contenuti, controllare lo stato e recuperare le traduzioni. Ora devi collegare questi passaggi in modo che la tua app sappia automaticamente quando recuperare le traduzioni.

Puoi farlo usando i callback (consigliato) o eseguendo un job che effettua il polling dello stato della traduzione.

Usare i callback (consigliato)

Quando invii il contenuto per la traduzione, puoi includere un URL di callback. PTC chiama questo URL al completamento della traduzione. Il tuo endpoint quindi recupera e memorizza le traduzioni.

Questo approccio è efficiente perché PTC ti avvisa immediatamente.

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

Eseguire il polling dello stato della traduzione (alternativa)

Non puoi usare i callback? Dopo aver inviato il contenuto per la traduzione, puoi mettere in coda un job in background che controlla ripetutamente lo stato della traduzione. Il job recupera le traduzioni una volta completate.

Questo approccio non è consigliato perché spreca risorse e aggiunge chiamate API non necessarie.

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

Inizia a tradurre la tua applicazione Rails

Ora hai tutto ciò che ti serve per integrare l'API di traduzione di PTC. Crea un account e traduci 20.000 parole in 2 lingue durante la prova.

In questa pagina

Prima di iniziare

Configura PTC e ottieni il tuo token API

Endpoint API per tradurre il contenuto dinamico

Inviare il contenuto per la traduzione

Controllare lo stato della traduzione

Recuperare le traduzioni

Ricevere una notifica quando le traduzioni sono pronte

Usare i callback (consigliato)

Eseguire il polling dello stato della traduzione (alternativa)

Pronto a iniziare a usare PTC? Iscriviti per una prova di 30 giorni.