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

נקודת קצה:

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

נקודת קצה:

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 יום בחינם.