Comment traduire du contenu dynamique dans Rails avec l’API PTC

Découvrez comment utiliser l’API PTC pour traduire du contenu dynamique dans votre application Ruby on Rails (RoR). Cela inclut les articles de blog, les informations produit et tout texte stocké dans votre base de données.

Ci-dessous, nous vous guidons à travers le processus de traduction de contenu dynamique dans des applications Rails en deux parties :

  • Tout d’abord, vous découvrirez les trois endpoints de l’API individuellement : comment envoyer du contenu à traduire, vérifier son statut et récupérer les traductions terminées.
  • Ensuite, vous verrez comment relier ces endpoints dans un workflow complet en utilisant soit des callbacks, soit le polling.

Avant de commencer

Ce guide suppose que vous disposez d’une application Rails configurée avec un moyen de stocker les traductions (comme Mobility, Globalize ou votre propre solution).

Si vous partez de zéro ou souhaitez voir une implémentation complète, nous avons créé une application Rails de démonstration qui montre l’intégration de PTC de bout en bout. La démo utilise :

Voir l’application de démonstration sur GitHub →

Configurer PTC et obtenir votre jeton d’API

Pour commencer, vous avez besoin d’un compte PTC et d’un jeton d’API :

  1. Inscrivez-vous à PTC. La création d’un compte est gratuite et vous pouvez traduire 20 000 mots vers 2 langues sans frais. Ensuite, vous payez uniquement ce que vous traduisez.
  2. Créez un nouveau projet et sélectionnez Intégration API.
  3. Copiez le jeton d’API que PTC génère à la fin de la configuration du projet. Vous en aurez besoin pour authentifier toutes les requêtes. Vous pouvez retrouver le même jeton dans le tableau de bord de votre projet, sous Settings → Manage API tokens.
Creating a new project in PTC
Creating a new project
Choosing API integration in PTC setup
Choosing API Integration
API token under Settings → Manage API tokens
API token under Settings → Manage API tokens
Creating a new project in PTC
Choosing API integration in PTC setup
API token under Settings → Manage API tokens

Endpoints d’API pour traduire du contenu dynamique

1

Envoyer du contenu à traduire

Pour traduire du contenu, utilisez l’endpoint Create Content Translation. Cela planifie la traduction de votre contenu et renvoie un identifiant que vous utiliserez pour suivre l’avancement et récupérer les résultats.

Endpoint :

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

Paramètres :

  • data (obligatoire) – Le contenu à traduire sous forme de hash
  • name (obligatoire) – Un libellé pour cette tâche de traduction (par exemple, "post-123-translation")
  • target_languages (facultatif) – Un tableau de codes de langue (par exemple, ["es", "fr", "de"])
  • callback_url (facultatif) – Une URL que PTC utilisera pour vous notifier une fois les traductions

Voici un exemple de service qui lance la traduction :

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

Pour obtenir les détails complets de la réponse, les codes d’erreur et des exemples supplémentaires, consultez la documentation de l’API Create Content Translation.

2

Vérifier le statut de la traduction

Pour vérifier si votre traduction est terminée, utilisez l’endpoint Get Content Translation Status. Il renvoie le statut actuel et l’avancement de la traduction.

Endpoint :

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

Paramètres :

  • id (obligatoire) – L’identifiant unique de la tâche de traduction de contenu à vérifier

Exemple de service dans 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 réponse inclut un champ de statut et un pourcentage indiquant l’avancement de la traduction. Pour obtenir les détails complets de la réponse, consultez la documentation de l’API Get Content Translation.

3

Récupérer les traductions

Une fois votre traduction terminée, utilisez l’endpoint Get Content Translations pour récupérer les résultats. Il renvoie votre contenu d’origine ainsi que des versions traduites pour chaque langue cible.

Endpoint :

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

Paramètres :

  • id (obligatoire) – L’identifiant unique de la tâche de traduction de contenu à récupérer

Exemple dans 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

Recevoir une notification lorsque les traductions sont prêtes

Vous avez appris à envoyer du contenu, vérifier le statut et récupérer les traductions. Vous devez maintenant relier ces étapes afin que votre application sache automatiquement quand récupérer les traductions.

Vous pouvez le faire en utilisant des callbacks (recommandé) ou en exécutant une tâche qui interroge le statut de la traduction (polling).

Utiliser des callbacks (recommandé)

Lorsque vous envoyez du contenu à traduire, vous pouvez inclure une URL de callback. PTC appelle cette URL lorsque la traduction est terminée. Votre endpoint récupère ensuite les traductions et les stocke.

C’est efficace, car PTC vous notifie immédiatement.

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

Interroger le statut de la traduction (alternative)

Vous ne pouvez pas utiliser de callbacks ? Après avoir envoyé du contenu à traduire, vous pouvez mettre en file d’attente une tâche en arrière-plan qui vérifie à plusieurs reprises le statut de la traduction. La tâche récupère les traductions une fois terminées.

Cette approche n’est pas recommandée, car elle gaspille des ressources et ajoute des appels d’API inutiles.

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

Commencez à traduire votre application Rails

Vous avez désormais tout ce qu’il vous faut pour intégrer l’API de traduction de PTC. Créez un compte gratuit et traduisez 20 000 mots vers 2 langues sans frais.

Commencer votre essai gratuit

Sur cette page

Avant de commencer

Configurer PTC et obtenir votre jeton d’API

Endpoints d’API pour traduire du contenu dynamique

Envoyer du contenu à traduire

Vérifier le statut de la traduction

Récupérer les traductions

Recevoir une notification lorsque les traductions sont prêtes

Utiliser des callbacks (recommandé)

Interroger le statut de la traduction (alternative)

Commencez à taper et appuyez sur Entrée pour rechercher

Faire défiler vers le haut