Scopri come usare l’API 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:
- Prima imparerai i tre endpoint API individualmente: come inviare contenuti per la traduzione, verificarne lo stato e recuperare le traduzioni completate.
- Poi vedrai come collegare questi endpoint in un flusso di lavoro completo usando callback o polling.
Prima di iniziare
Questa guida presuppone che tu abbia un’applicazione Rails configurata con un modo 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 PTC end-to-end. 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:
- Registrati a PTC. Creare un account è gratuito e puoi tradurre 20.000 parole in 2 lingue senza costi. Poi paghi per ciò che traduci.
- Crea un nuovo progetto e seleziona Integrazione API.
- 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 nella dashboard del tuo progetto sotto Impostazioni → Gestisci token API.
Endpoint API per tradurre contenuti dinamici
1
Invia contenuti per la traduzione
Per tradurre contenuti, usa l’endpoint Create Content Translation. Questo pianifica i tuoi contenuti per la traduzione e restituisce un ID che userai per monitorare i progressi e recuperare i risultati.
Endpoint:
POST https://app.ptc.wpml.org/api/v1/content_translationParametri:
data(obbligatorio) – Il contenuto da tradurre come hashname(obbligatorio) – Un’etichetta per questo lavoro di traduzione (ad esempio,"post-123-translation")target_languages(facoltativo) – Un array di codici lingua (ad esempio,["es", "fr", "de"])callback_url(facoltativo) – Un URL dove PTC ti avviserà una volta completate le traduzioni
Ecco un esempio di servizio che avvia la traduzione:
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 dettagli completi sulla risposta, codici di errore ed esempi aggiuntivi, consulta la documentazione API Create Content Translation.
2
Verifica lo stato della traduzione
Per verificare se la tua traduzione è completa, usa l’endpoint Get Content Translation Status. Questo restituisce lo stato attuale e i progressi della traduzione.
Endpoint:
GET https://app.ptc.wpml.org/api/v1/content_translation/{id}/statusParametri:
id(obbligatorio) – L’identificatore univoco del lavoro di traduzione dei contenuti da verificare
Esempio di servizio in Rails:
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 i progressi della traduzione. Per dettagli completi sulla risposta, consulta la documentazione API Get Content Translation.
3
Recupera 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 lavoro di traduzione dei contenuti da recuperare
Esempio in Rails:
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
Ricevi una notifica quando le traduzioni sono pronte
Hai imparato come inviare contenuti, verificare 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 lavoro che effettua il polling dello stato della traduzione.
Uso dei callback (consigliato)
Quando invii contenuti per la traduzione, puoi includere un URL di callback. PTC chiama questo URL quando la traduzione è completata. Il tuo endpoint recupera e memorizza quindi le traduzioni.
Questo è efficiente perché PTC ti avvisa immediatamente.
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 contenuti per la traduzione, puoi mettere in coda un lavoro in background che verifica ripetutamente lo stato della traduzione. Il lavoro recupera le traduzioni quando sono complete.
Questo approccio non è consigliato perché spreca risorse e aggiunge chiamate API non necessarie.
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ò di cui hai bisogno per integrare l’API di traduzione di PTC. Crea un account gratuito e traduci 20.000 parole in 2 lingue senza costi.
