Tafsiri yaliyopangwa kutoka Ruby kwa kutumia gem ya PolyLingo

Gem ya PolyLingo ya Ruby sasa inapatikana kwenye RubyGems. Inashughulikia uso wote wa API ya PolyLingo: tafsiri ya sinkroni, maombi ya kundi, kazi za asinkroni zenye polling, na vituo vyote vya huduma. Haina utegemezi wowote wa wakati wa utekelezaji na inahitaji Ruby 2.7 au baadaye.

Chapisho hili linaelezea jinsi ya kusakinisha, usanidi wa mteja, na kila njia inayopatikana katika gem.

Usakinishaji

Ongeza kwenye Gemfile yako:

gem "polylingo"

Kisha endesha:

bundle install

Au sakinisha moja kwa moja:

gem install polylingo

Hakuna utegemezi wa wakati wa utekelezaji. Gem hutumia tu maktaba ya kawaida ya Ruby kwa HTTP.

Kuweka mteja

require "polylingo"

client = PolyLingo.new(api_key: ENV.fetch("POLYLINGO_API_KEY"))

Mipangilio miwili ya hiari inapatikana:

client = PolyLingo.new(
  api_key:  ENV.fetch("POLYLINGO_API_KEY"),
  base_url: "https://api.usepolylingo.com/v1", # chaguo-msingi, badilisha kwa matoleo yanayojimiliki
  timeout:  120,                               # sekunde (fungua + soma), chaguo-msingi 120
)

Hifadhi ufunguo wako wa API katika mabadiliko ya mazingira. Usihardcode kamwe na usiwekee kwenye udhibiti wa toleo.

Kutafsiri yaliyomo

Ombi moja

Pitia yaliyomo yako, safu ya misimbo ya lugha lengwa, na muundo wa hiari:

result = client.translate(
  content: "# Habari\n\nHii ni yaliyomo **yaliyopangwa**.",
  targets: %w[es fr de],
  format:  "markdown"
)

puts result["translations"]["es"]
puts result["usage"]["total_tokens"]

Kigezo cha format kinakubali plain, markdown, json, au html. Ikiwa hakitatolewa, API itagundua muundo kiotomatiki. Pia unaweza kupitisha source kama kidokezo cha lugha na model kama "standard" (chaguo-msingi) au "advanced".

Uhifadhi wa muundo hufanya kazi sawa na sehemu nyingine za API ya PolyLingo. Kwa json, thamani za aina ya string pekee ndizo zinazotafsiriwa na funguo, uingizaji, na aina zisizo za string hazibadiliki. Kwa markdown, vichwa vinabaki vichwa na sehemu za msimbo zinahifadhiwa kama zilivyo. Kwa html, lebo na sifa zinahifadhiwa na nodi za maandishi pekee ndizo zinazotafsiriwa.

Kutafsiri faili la eneo la JSON

require "json"

source = JSON.parse(File.read("config/locales/en.yml"))

result = client.translate(
  content: source.to_json,
  format:  "json",
  targets: %w[fr de ja]
)

%w[fr de ja].each do |locale|
  translated = JSON.parse(result["translations"][locale])
  File.write(
    "config/locales/#{locale}.json",
    JSON.pretty_generate(translated)
  )
  puts "Imeandika config/locales/#{locale}.json"
end

Ombi moja hushughulikia maeneo yote matatu. Funguo ni sawa na chanzo katika kila faili ya pato.

Maombi ya kundi

Tuma hadi vitu 100 vya yaliyomo katika ombi moja, kila kikiwa na id yake na format ya hiari:

result = client.batch(
  items: [
    { id: "hero_title",    content: "Karibu tena",   format: "plain" },
    { id: "hero_subtitle", content: "Hapa ni mabadiliko ya leo", format: "plain" },
    { id: "cta",           content: "Anza sasa",    format: "plain" },
  ],
  targets: %w[es fr de]
)

result["results"].each do |row|
  puts "#{row["id"]}: #{row["translations"]["es"]}"
end

Vitu vyote vinashiriki safu moja ya targets. id unayotuma huhifadhiwa katika jibu ili uweze kuoanisha matokeo na data yako ya chanzo bila kutegemea mpangilio.

Kazi za asinkroni

Kwa tafsiri za muda mrefu, API ya kazi inakubali ombi, inarudisha job_id mara moja, na inakuwezesha kufanya polling kwa matokeo. Gem inashughulikia hili kwa njia mbili.

Weka kwenye foleni na fanya polling kwa mikono

accepted = client.jobs.create(
  content: File.read("content/long-article.md"),
  targets: %w[es fr de ja zh],
  format:  "markdown"
)

job_id = accepted["job_id"]

loop do
  sleep 5
  state = client.jobs.get(job_id)
  break if %w[complete failed].include?(state["status"])
end

if state["status"] == "complete"
  translations = state["translations"]
end

Mwito mmoja unaofanya polling hadi ukamilike

done = client.jobs.translate(
  content:       File.read("content/long-article.md"),
  targets:       %w[es fr de],
  format:        "markdown",

  # Mabadiliko ya hiari (chaguo-msingi yanaonyeshwa):
  poll_interval: 5,    # sekunde kati ya polling, chaguo-msingi 5
  timeout:       1200, # bajeti ya jumla ya kusubiri kwa sekunde, chaguo-msingi 1200 (dakika 20)
  on_progress:   ->(queue_position) { puts "Nafasi kwenye foleni: #{queue_position.inspect}" }
)

translations = done["translations"]
usage        = done["usage"]

Thamani zote za muda katika gem ya Ruby hutumia sekunde, sambamba na mila ya Ruby. Lambda on_progress huanzishwa kila polling na hupokea nafasi ya foleni ya sasa kama nambari kamili, au nil ikiwa API haitoi.

Vituo vya huduma

health    = client.health
# => { "status" => "ok", "timestamp" => "..." }

languages = client.languages
# => { "languages" => [{ "code" => "en", "name" => "English", "rtl" => false }, ...] }

usage     = client.usage
# => { "usage" => { "tokens_used" => 12000, "tokens_remaining" => 38000, ... } }

health na languages hazihitaji ufunguo wa API. usage inarudisha matumizi ya tokeni kwa mwezi wa kalenda wa sasa kwa akaunti iliyothibitishwa.

Kushughulikia makosa

Makosa yote yanarithi kutoka PolyLingo::PolyLingoError. Kamata madarasa maalum unayotaka kushughulikia:

begin
  result = client.translate(
    content: "# Habari",
    targets: %w[es],
    format:  "markdown"
  )
rescue PolyLingo::AuthError => e
  # HTTP 401 — ufunguo wa API batili, umekosekana, au umefutwa
  puts "Uthibitishaji umefaulu: #{e.message}"
rescue PolyLingo::RateLimitError => e
  # HTTP 429 — kikomo cha kwa dakika kimefikiwa
  retry_after = e.retry_after # sekunde kamili au nil
  sleep retry_after if retry_after
  retry
rescue PolyLingo::JobFailedError => e
  # Kazi ya asinkroni imefikia hali ya mwisho ya kushindwa, au polling imekwisha muda
  puts "Kazi imefaulu: #{e.job_id}"
rescue PolyLingo::PolyLingoError => e
  # Makosa mengine yote ya API
  puts "#{e.status}: #{e.error} — #{e.message}"
end

RateLimitError#retry_after inarudisha nambari kamili kutoka kwa mwili wa jibu la JSON au kichwa cha Retry-After, chochote kilichopo, au nil ikiwa hakuna. JobFailedError#job_id inakupa ID ya kazi iliyoshindwa inapojulikana.

Marejeleo ya haraka

Njia	Endpoint	Inahitaji uthibitisho
`client.health`	GET /health	Hapana
`client.languages`	GET /languages	Hapana
`client.translate(...)`	POST /translate	Ndiyo
`client.batch(...)`	POST /translate/batch	Ndiyo
`client.usage`	GET /usage	Ndiyo
`client.jobs.create(...)`	POST /jobs	Ndiyo
`client.jobs.get(job_id)`	GET /jobs/:id	Ndiyo
`client.jobs.translate(...)`	POST /jobs + polling	Ndiyo

Anza sasa

Gem iko kwenye RubyGems kwenye rubygems.org/gems/polylingo. Chanzo cha msimbo kiko kwenye github.com/UsePolyLingo/polylingo-ruby. Nyaraka kamili za API ziko kwenye usepolylingo.com/docs.

Ngazi ya bure inajumuisha tokeni 50,000 kwa mwezi. Hakuna kadi ya mkopo inahitajika.

gem install polylingo

Pata ufunguo wako wa API

Tafsiri yaliyomo yaliyopangwa kutoka Ruby kwa kutumia gem ya PolyLingo