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

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

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

• ראשית, תלמדו על שלוש נקודות הקצה של ה־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 מייצרת בסיום הגדרת הפרויקט. תזדקקו לטוקן זה כדי לאמת את כל הבקשות. תוכלו למצוא את אותו הטוקן בלוח הבקרה של הפרויקט שלכם תחת הגדרות → ניהול אסימוני API.

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

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

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

נקודת קצה:

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 תודיע לכם ברגע שהתרגומים יהיו מוכנים

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

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. היא מחזירה את הסטטוס הנוכחי ואת התקדמות התרגום.

נקודת קצה:

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

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

אחזור תרגומים

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

נקודת קצה:

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 (מומלץ) או על ידי הרצת משימה שמבצעת 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? לאחר שליחת תוכן לתרגום, תוכלו להכניס לתור משימת רקע שבודקת שוב ושוב את סטטוס התרגום. המשימה מושכת את התרגומים עם השלמתם.

גישה זו אינה מומלצת מכיוון שהיא מבזבזת משאבים ומוסיפה קריאות 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 יום.