Come tradurre contenuti dinamici in Rails utilizzando l'API di PTC

Scopri come utilizzare l'API di PTC per tradurre contenuti dinamici nella tua applicazione Ruby on Rails (RoR). Questo include post di blog, informazioni sui prodotti e qualsiasi testo memorizzato nel tuo database.

Di seguito, ti guideremo attraverso il processo di traduzione dei contenuti dinamici nelle applicazioni Rails in due parti:

In primo luogo, imparerai a conoscere singolarmente i tre endpoint API: come inviare i contenuti per la traduzione, come controllarne lo stato e come recuperare le traduzioni completate.
Successivamente, vedrai come collegare questi endpoint in un workflow completo utilizzando 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 personalizzata).

Se stai partendo da zero o vuoi vedere un'implementazione completa, abbiamo creato un'applicazione Rails demo che mostra l'integrazione di PTC end-to-end. La demo utilizza:

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:

Registrati a PTC. La creazione di un account è gratuita e puoi tradurre 20.000 parole in 2 lingue senza costi. Successivamente, paghi per ciò che traduci.
Crea un nuovo progetto e seleziona API Integration.
Copia il token API che PTC genera al termine 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 sotto Settings → Manage API tokens.

Creating a new project in PTC — Creazione di un nuovo progetto

Choosing API integration in PTC setup — Scelta di API Integration

API token under Settings → Manage API tokens — Token API sotto Settings → Manage API tokens

Endpoint API per la traduzione di contenuti dinamici

Inviare contenuti per la traduzione

Per tradurre i contenuti, utilizza l'endpoint Create Content Translation. Questo pianifica la traduzione dei tuoi contenuti e restituisce un ID che utilizzerai per monitorare l'avanzamento e recuperare i risultati.

Endpoint:

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

Parametri:

data (obbligatorio) – Il contenuto da tradurre sotto forma di hash
name (obbligatorio) – Un'etichetta per questo lavoro 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 dove PTC ti invierà una notifica una volta che le traduzioni saranno pronte

Ecco un esempio di servizio 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 sulla risposta, i codici di errore e altri esempi, consulta la documentazione API di Create Content Translation.

Controllare lo stato della traduzione

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

Endpoint:

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

Parametri:

id (obbligatorio) – L'identificatore univoco del lavoro di traduzione dei contenuti da controllare

Esempio di servizio 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 status e una percentuale che mostra l'avanzamento della traduzione. Per i dettagli completi sulla risposta, consulta la documentazione API di Get Content Translation Status.

Recuperare le traduzioni

Una volta completata la traduzione, utilizza 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 lavoro di traduzione dei contenuti 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 notifiche quando le traduzioni sono pronte

Hai imparato come inviare 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 utilizzando i callback (scelta consigliata) o eseguendo un job che effettua il polling dello stato della traduzione.

Utilizzo dei callback (scelta consigliata)

Quando invii contenuti per la traduzione, puoi includere un URL di callback. PTC chiama questo URL quando la traduzione è completata. Il tuo endpoint quindi recupera e memorizza le traduzioni.

Questo metodo è 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

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 è raccomandato 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 gratuito e traduci 20.000 parole in 2 lingue senza costi.

In questa pagina

Prima di iniziare

Configura PTC e ottieni il tuo token API

Endpoint API per la traduzione di contenuti dinamici

Inviare contenuti per la traduzione

Controllare lo stato della traduzione

Recuperare le traduzioni

Ricevere notifiche quando le traduzioni sono pronte

Utilizzo dei callback (scelta consigliata)

Polling dello stato della traduzione (alternativa)

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