আপনাকে সবকিছু পুনরায় অনুবাদ করতে হবে না: CI-তে ডেল্টা অনুবাদ কিভাবে কাজ করে

যখন আপনি আপনার CI পাইপলাইনে স্বয়ংক্রিয় অনুবাদ সংযুক্ত করবেন, তখন একটি স্বাভাবিক প্রশ্ন দ্রুত উঠে আসে: কেউ যখন পরিবর্তন পুশ করে, তখন কি এটি প্রতিবার পুরো লোকেল ফাইলটি পুনরায় অনুবাদ করে?

ডেল্টা মোড ছাড়া, হ্যাঁ। আপনার সোর্স লোকেল ফাইল স্পর্শ করা প্রতিটি পুশ API-তে পুরো ফাইলটি পাঠায়, প্রতিটি কী, প্রতিটি স্ট্রিং, তা পরিবর্তিত হোক বা না হোক। একটি ছোট প্রকল্পের জন্য যা শুরুতে ঠিক আছে। একটি পরিপক্ক প্রকল্পের জন্য যেখানে শত শত অনুবাদ কী ১০ বা ২০ ভাষায় রয়েছে, আপনি এমন স্ট্রিংগুলিতে টোকেন নষ্ট করছেন যা শেষ রান থেকে পরিবর্তিত হয়নি এবং বিনিময়ে একই আউটপুট পাচ্ছেন।

ডেল্টা অনুবাদ এটি সমাধান করে। পুরো ফাইল পাঠানোর পরিবর্তে, অ্যাকশন আপনার বর্তমান সোর্স ফাইলকে একটি সংরক্ষিত বেসলাইন এর সাথে তুলনা করে, শুধুমাত্র যোগ বা পরিবর্তিত কী গুলো সনাক্ত করে এবং সেগুলোই API-তে পাঠায়। অপরিবর্তিত কী গুলোর আউটপুট বিদ্যমান অনুবাদিত ফাইল থেকে নেওয়া হয়। টোকেন ব্যবহারের পরিমাণ প্রকৃত কাজের সাথে মিলিয়ে কমে যায়।

বেসলাইন কিভাবে কাজ করে

যখন ডেল্টা মোড প্রথমবার চালানো হয়, অথবা আপনি পূর্ণ রিফ্রেশ জোর করেন, তখন অ্যাকশন সম্পূর্ণ সোর্স ফাইল অনুবাদ করে এবং একটি সমতল JSON উপস্থাপনা হিসাবে এটি আপনার রিপোজিটরিতে একটি বেসলাইন ফাইল হিসেবে সংরক্ষণ করে। পরবর্তী রান গুলোতে, অ্যাকশন সেই বেসলাইন লোড করে, বর্তমান সোর্স ফাইলের সাথে তুলনা করে, এবং শুধুমাত্র পরিবর্তিত কী গুলো নিয়ে একটি পে-লোড তৈরি করে।

JSON লোকেল ফাইলের জন্য বেসলাইন .polylingo-baseline.json নামে আপনার মেসেজ ডিরেক্টরিতে সংরক্ষিত হয়। YAML লোকেল ফাইলের জন্য এটি .polylingo-yaml-baseline.json নামে আপনার লোকেলস ডিরেক্টরিতে থাকে। Laravel PHP lang ফাইলের জন্য এটি .polylingo-laravel-php-baseline.json নামে আপনার lang ডিরেক্টরিতে থাকে।

বেসলাইন আপনার অনুবাদিত ফাইলগুলোর সাথে কমিট করা হয় যাতে এটি রিপোজিটরির সাথে থাকে। যে কোনো ডেভেলপার রিপো ক্লোন করলে একই বেসলাইন পায় যা পাইপলাইন ব্যবহার করছে।

কী পরিবর্তন হিসেবে গণ্য হয়

ডিফ আপনার সোর্স ফাইলের সমতল কী উপস্থাপনার উপর কাজ করে। নেস্টেড স্ট্রাকচারগুলো তুলনার আগে ডট-নোটেশন কী গুলোতে সমতল করা হয়:

{
  "nav.home": "হোম",
  "nav.about": "আমাদের সম্পর্কে",
  "hero.title": "আমাদের প্ল্যাটফর্মে স্বাগতম",
  "hero.cta": "শুরু করুন"
}

একটি কী ডেল্টা পে-লোডে অন্তর্ভুক্ত হয় যদি:

এটি বর্তমান সোর্স ফাইলে আছে কিন্তু বেসলাইনে নেই (নতুন কী)
এটি উভয় জায়গায় আছে কিন্তু মান পরিবর্তিত হয়েছে (পরিবর্তিত কী) বেসলাইনে থাকা কিন্তু বর্তমান সোর্স ফাইলে না থাকা কী (মুছে ফেলা কী) স্বয়ংক্রিয়ভাবে অনুবাদিত আউটপুট ফাইল থেকে সরিয়ে ফেলা হয়। উভয় জায়গায় একই কী সম্পূর্ণরূপে এড়ানো হয় এবং তাদের বিদ্যমান অনুবাদ অপরিবর্তিত থাকে।

এটি বাস্তবে কেমন দেখায়

ধরুন আপনার একটি Next.js প্রকল্প আছে যার messages/en.json এ ২০০টি অনুবাদ কী রয়েছে, যা ইতিমধ্যে ১২টি ভাষায় অনূদিত। একজন ডেভেলপার হিরো সেকশনের কপি আপডেট করে এবং একটি ফিচার ঘোষণা জন্য দুইটি নতুন কী যোগ করে। অর্থাৎ ২০০ থেকে ৪টি কী পরিবর্তিত হয়েছে।

ডেল্টা মোড ছাড়া, পাইপলাইন প্রতিটি পুশে ১২টি ভাষায় গুণিত ২০০টি কী পাঠায়। ডেল্টা মোডে এটি ৪টি কী পাঠায়। সেই রানটির জন্য টোকেন ব্যবহার প্রায় ২% যা একটি পূর্ণ অনুবাদের খরচ হবে। পাইপলাইনও দ্রুত কারণ পাঠানোর এবং অপেক্ষার পরিমাণ কম।

নিয়মিত উন্নয়নের এক মাসে, সঞ্চয় উল্লেখযোগ্যভাবে বৃদ্ধি পায়। বেশিরভাগ পুশ কয়েকটি স্ট্রিং স্পর্শ করে। পূর্ণ পুনরায় অনুবাদ তখনই হয় যখন আপনি একটি নতুন ভাষা যোগ করেন বা স্পষ্টভাবে বেসলাইন রিসেট করেন।

তিনটি PolyLingo GitHub অ্যাকশন

ডেল্টা মোড সব তিনটি PolyLingo অনুবাদ অ্যাকশনে উপলব্ধ। প্রতিটি একটি নির্দিষ্ট কন্টেন্ট টাইপ এবং প্রকল্প কাঠামোর জন্য তৈরি।

translateAction — JSON এবং Markdown

মূল অ্যাকশন। next-intl এবং i18next স্টাইলে সমতল JSON লোকেল ফাইল পরিচালনা করে, বড় ফাইলের জন্য async jobs API এর মাধ্যমে ঐচ্ছিক Markdown ডকুমেন্টেশন পাস সহ।

- uses: UsePolyLingo/translate-action@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es,ja,zh
    delta: true
    commit: true
    commit_message: "chore(i18n): sync translations"

ডেল্টা বেসলাইন: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — মার্কেটপ্লেসে দেখুন

translate-action-yaml — YAML লোকেল ফাইল

নেস্টেড YAML লোকেল ফাইল ব্যবহারকারী প্রকল্পের জন্য: Rails i18n, Vue i18n, এবং YAML ফরম্যাট ব্যবহারকারী অন্য যেকোন ফ্রেমওয়ার্ক। অ্যাকশন Rails এর রুট লোকেল কী স্বয়ংক্রিয়ভাবে পরিচালনা করে — en.yml এ একটি en: রুট কী থাকে, এবং প্রতিটি আউটপুট ফাইল সঠিক টার্গেট লোকেল কী পায় (fr:, de: ইত্যাদি)।

PolyLingo API JSON এর সাথে নেটিভ কাজ করে, তাই অ্যাকশন নেস্টেড YAML কে ডট-নোটেশন JSON এ সমতল করে পাঠায়, অনুবাদ করে, তারপর নেস্টেড স্ট্রাকচার পুনর্গঠন করে এবং বৈধ YAML আউটপুট লেখে। v1 এর একটি সতর্কতা: ডট ধারণকারী কী গুলো স্বাভাবিকভাবেই সমর্থিত নয়, কারণ এগুলো ডট-নোটেশন সমতলকরণের সাথে সংঘর্ষ করে।

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    source_file: config/locales/en.yml
    locales: fr,de,es,ja
    delta: true
    commit: true

ডেল্টা বেসলাইন: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — মার্কেটপ্লেসে দেখুন

translate-action-laravel — Laravel lang ফাইল

Laravel প্রকল্পের জন্য যা JSON অনুবাদ ফাইল (lang/en.json, Laravel 9+ স্টাইলে নেস্টেড এবং সমতল স্ট্রাকচার উভয়ই সমর্থন করে) অথবা PHP অ্যারে lang ফাইল (lang/en/*.php) ব্যবহার করে। অ্যাকশন স্বয়ংক্রিয়ভাবে আপনার প্রকল্প কোন ফরম্যাট ব্যবহার করে তা php_format: auto দ্বারা সনাক্ত করে — প্রথমে lang/en.json চেক করে, না পেলে PHP অ্যারে ফাইল ব্যবহার করে।

PHP ফাইলের জন্য এটি PHP CLI ব্যবহার করে সোর্স ফাইল পড়ে এবং অনুবাদিত আউটপুটকে বৈধ PHP অ্যারে সিনট্যাক্সে সিরিয়ালাইজ করে JavaScript এ, কোন অতিরিক্ত নির্ভরতা ছাড়াই। GitHub হোস্টেড ubuntu-latest রানার PHP 8.x ডিফল্টরূপে অন্তর্ভুক্ত করে তাই অতিরিক্ত সেটআপ প্রয়োজন হয় না। PHP 7.4 বা তার পরের সংস্করণ প্রয়োজন।

v1 এর একটি সতর্কতা: PHP মোডে ডট ধারণকারী কী গুলো সমর্থিত নয় ডট-নোটেশন সমতলকরণের কারণে।

- uses: UsePolyLingo/translate-action-laravel@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    lang_dir: lang
    source_locale: en
    locales: fr,de,es,pt,nl
    php_format: auto
    delta: true
    open_pr: true

ডেল্টা বেসলাইন: lang/.polylingo-laravel-json-baseline.json অথবা lang/.polylingo-laravel-php-baseline.json ফরম্যাট অনুসারে।

github.com/UsePolyLingo/translate-action-laravel — মার্কেটপ্লেসে দেখুন

PR মোড বনাম কমিট মোড

তিনটি অ্যাকশনই দুইটি আউটপুট মোড সমর্থন করে।

কমিট মোড (commit: true) অনুবাদিত ফাইলগুলো লেখে এবং সেগুলো সরাসরি বর্তমান ব্রাঞ্চে কমিট করে। সহজ সেটআপ, এমন দলের জন্য ভালো যারা অনুবাদকে একটি স্বয়ংক্রিয় প্রক্রিয়া হিসেবে দেখে যা পর্যালোচনা প্রয়োজন হয় না।

PR মোড (open_pr: true) একটি নতুন ব্রাঞ্চ তৈরি করে (polylingo/yaml-<sha>, polylingo/laravel-<sha> ইত্যাদি), সেখানে অনুবাদিত ফাইলগুলো লেখে, এবং আপনার বেস ব্রাঞ্চের বিরুদ্ধে একটি পুল রিকোয়েস্ট খুলে। এমন দলের জন্য ভালো যারা অনুবাদিত বিষয়বস্তু মার্জ করার আগে মানব পর্যালোচনা চান, অথবা এমন প্রকল্পের জন্য যেখানে অনুবাদের গুণগত মান সরাসরি ব্যবহারকারীর অভিজ্ঞতাকে প্রভাবিত করে।

যখন উভয় সেট করা হয়, PR মোড জিতে যায়।

PR মোডের জন্য আপনার ওয়ার্কফ্লো অনুমতিতে pull-requests: write থাকা প্রয়োজন:

permissions:
  contents: write
  pull-requests: write

পূর্ণ রিফ্রেশ জোর করা

ডেল্টা মোড সংরক্ষিত বেসলাইনের সাথে তুলনা করে। আপনি যদি বেসলাইন যাই বলুক না কেন সবকিছু পুনরায় অনুবাদ করতে চান, তাহলে delta: false সেট করুন। এটি বেসলাইনকেও আপডেট করে যাতে পরবর্তী ডেল্টা রানগুলো নতুন অবস্থান থেকে শুরু হয়।

পূর্ণ রিফ্রেশ তখন উপকারী যখন আপনি একটি নতুন লক্ষ্য ভাষা যোগ করেন, নতুন মডেল ভার্সনে অনুবাদের গুণগত মান উন্নতি পেতে চান, অথবা যেকোন কারণে বেসলাইন বাস্তবতা থেকে বিচ্যুত হয়েছে।

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    locales: fr,de,es,ja,zh,ko,ar
    delta: false  # পূর্ণ রিফ্রেশ, বেসলাইন আপডেট করে
    commit: true

পরবর্তী ধাপের জন্য আউটপুট

তিনটি অ্যাকশনই একই আউটপুট প্রকাশ করে যাতে আপনি সেগুলো পরবর্তী ওয়ার্কফ্লো ধাপে ব্যবহার করতে পারেন:

- uses: UsePolyLingo/translate-action@v1
  id: translate
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es
    delta: true
    commit: true

- name: Log translation stats
  run: |
    echo "Locales translated: ${{ steps.translate.outputs.locales_translated }}"
    echo "Files changed: ${{ steps.translate.outputs.files_changed }}"
    echo "Tokens used: ${{ steps.translate.outputs.tokens_used }}"

প্রতিটি রান GitHub Actions স্টেপ সামারিতে একটি সারাংশ টেবিলও লেখে যাতে আপনি লগ খুঁজে না পেয়ে টোকেন ব্যবহার এবং অনুবাদ ফলাফল দেখতে পারেন।

শুরু করা

তিনটি অ্যাকশনই GitHub মার্কেটপ্লেসে উপলব্ধ। আপনাকে একটি PolyLingo API কী লাগবে, যা usepolylingo.com এ বিনামূল্যে পাওয়া যায়। ফ্রি টিয়ারে প্রতি মাসে ৫০,০০০ টোকেন অন্তর্ভুক্ত। ডেল্টা মোড চালু থাকলে, বেশিরভাগ প্রকল্প নিয়মিত উন্নয়ন পুশে এর মধ্যে থাকবে।

আপনার API কী রিপোজিটরি সিক্রেট হিসেবে যোগ করুন (POLYLINGO_API_KEY) এবং প্রাসঙ্গিক অ্যাকশনটি আপনার ওয়ার্কফ্লোতে যোগ করুন। প্রথম রানটি একটি পূর্ণ অনুবাদ করে এবং বেসলাইন সেট করে। এরপরের প্রতিটি রান শুধুমাত্র পরিবর্তিত অংশ অনুবাদ করে।

আপনাকে সবকিছু পুনরায় অনুবাদ করতে হবে না: সিআই-তে ডেল্টা অনুবাদ কীভাবে কাজ করে