כיצד לתרגם תוכן דינמי ב־Rails באמצעות ה־API של PTC

למדו כיצד להשתמש ב־API של PTC כדי לתרגם תוכן דינמי באפליקציית Ruby on Rails (RoR) שלכם. זה כולל פוסטים בבלוג, מידע על מוצרים וכל טקסט המאוחסן במסד הנתונים שלכם.

להלן נדריך אתכם בתהליך של תרגום תוכן דינמי באפליקציות Rails בשני חלקים:

• ראשית, תלמדו על שלוש נקודות הקצה (endpoints) של ה־API בנפרד – כיצד לשלוח תוכן לתרגום, לבדוק את הסטטוס שלו ולקבל תרגומים שהושלמו.
• לאחר מכן, תראו כיצד לחבר את נקודות הקצה הללו לתהליך עבודה מלא באמצעות callbacks או polling.

לפני שתתחילו

מדריך זה מניח שיש לכם אפליקציית Rails מוגדרת עם דרך לאחסן תרגומים (כמו Mobility, Globalize או פתרון משלכם).

אם אתם מתחילים מאפס או רוצים לראות מימוש מלא, בנינו אפליקציית Rails לדוגמה המציגה אינטגרציה עם PTC מקצה לקצה. הדוגמה משתמשת ב־:

• Mobility לאחסון תרגומים
• dotenv-rails עבור משתני סביבה
• delayed_job_active_record לעיבוד ברקע

הגדרת PTC וקבלת טוקן API

כדי להתחיל, עליכם להיות בעלי חשבון PTC וטוקן API:

1. הירשמו ל־PTC. יצירת חשבון היא בחינם, ותוכלו לתרגם 20,000 מילים ל־2 שפות ללא עלות. לאחר מכן, תשלמו על מה שתרגמתם.
2. צרו פרויקט חדש ובחרו ב־API integration.
3. העתיקו את טוקן ה־API ש־PTC מייצר בסיום הגדרת הפרויקט. תזדקקו לטוקן זה כדי לאמת את כל הבקשות. תוכלו למצוא את אותו טוקן בלוח הבקרה של הפרויקט תחת Settings → Manage API tokens.

נקודות קצה ב־API לתרגום תוכן דינמי

שליחת תוכן לתרגום

כדי לתרגם תוכן, השתמשו בנקודת הקצה Create Content Translation. פעולה זו מתזמנת את התוכן שלכם לתרגום ומחזירה מזהה (ID) שבו תשתמשו כדי לעקוב אחר ההתקדמות ולקבל את התוצאות.

נקודת קצה (Endpoint):

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

פרמטרים:

• data (חובה) – התוכן לתרגום כ־hash
• name (חובה) – תווית עבור עבודת תרגום זו (למשל, "post-123-translation")
• target_languages (אופציונלי) – מערך של קודי שפה (למשל, ["es", "fr", "de"])
• callback_url (אופציונלי) – כתובת URL שבה PTC תעדכן אתכם ברגע שהתרגומים מוכנים

הנה דוגמה לשירות (service) שמתחיל את התרגום:

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

לפרטי תגובה מלאים, קודי שגיאה ודוגמאות נוספות, עיינו בתיעוד ה־API של Create Content Translation.

בדיקת סטטוס התרגום

כדי לבדוק אם התרגום שלכם הושלם, השתמשו בנקודת הקצה Get Content Translation Status. פעולה זו מחזירה את הסטטוס הנוכחי ואת התקדמות התרגום.

נקודת קצה (Endpoint):

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

פרמטרים:

• id (חובה) – המזהה הייחודי של עבודת תרגום התוכן שברצונכם לבדוק

דוגמה לשירות ב־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

התגובה כוללת שדה status ואחוז המציג את התקדמות התרגום. לפרטי תגובה מלאים, עיינו בתיעוד ה־API של Get Content Translation Status.

קבלת התרגומים

ברגע שהתרגום שלכם הושלם, השתמשו בנקודת הקצה Get Content Translations כדי למשוך את התוצאות. פעולה זו מחזירה את תוכן המקור שלכם בתוספת הגרסאות המתורגמות לכל שפת יעד.

נקודת קצה (Endpoint):

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

פרמטרים:

• id (חובה) – המזהה הייחודי של עבודת תרגום התוכן שברצונכם לקבל

דוגמה ב־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

קבלת התראה כשהתרגומים מוכנים

למדתם כיצד לשלוח תוכן, לבדוק סטטוס ולקבל תרגומים. כעת עליכם לחבר את השלבים הללו כך שהאפליקציה שלכם תדע אוטומטית מתי למשוך את התרגומים.

תוכלו לעשות זאת באמצעות callbacks (מומלץ) או על ידי הרצת job שמבצע polling לסטטוס התרגום.

שימוש ב־Callbacks (מומלץ)

כשאתם שולחים תוכן לתרגום, תוכלו לכלול כתובת callback URL. ‏PTC קוראת לכתובת זו כשהתרגום מסתיים. נקודת הקצה שלכם מושכת אז את התרגומים ומאחסנת אותם.

זוהי שיטה יעילה מכיוון ש־PTC מעדכנת אתכם באופן מיידי.

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 לסטטוס התרגום (חלופה)

לא יכולים להשתמש ב־callbacks? לאחר שליחת תוכן לתרגום, תוכלו להכניס לתור background job שבודק שוב ושוב את סטטוס התרגום. ה־job מושך את התרגומים כשהם מוכנים.

גישה זו אינה מומלצת מכיוון שהיא מבזבזת משאבים ומוסיפה קריאות API מיותרות.

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

התחילו לתרגם את אפליקציית ה־Rails שלכם

כעת יש לכם את כל מה שצריך כדי לבצע אינטגרציה עם API התרגום של PTC. צרו חשבון חינם ותרגמו 20,000 מילים ל־2 שפות ללא עלות.

בעמוד זה

לפני שתתחילו

הגדרת PTC וקבלת טוקן API

נקודות קצה ב־API לתרגום תוכן דינמי

שליחת תוכן לתרגום

בדיקת סטטוס התרגום

קבלת התרגומים

קבלת התראה כשהתרגומים מוכנים

שימוש ב־Callbacks (מומלץ)

ביצוע Polling לסטטוס התרגום (חלופה)

מוכנים להתחיל להשתמש ב־PTC? הירשמו לתקופת ניסיון של 30 יום בחינם.