आपको सब कुछ फिर से अनुवाद करने की जरूरत नहीं है: CI में डेल्टा अनुवाद कैसे काम करता है

एक बार जब आपने अपने CI पाइपलाइन में स्वचालित अनुवाद जोड़ लिया, तो एक स्वाभाविक सवाल जल्दी उठता है: क्या यह हर बार कोई बदलाव पुश करने पर पूरे लोकल फाइल को फिर से अनुवादित करता है?

डेल्टा मोड के बिना, हाँ। हर पुश जो आपके स्रोत लोकल फाइल को छूता है, पूरे फाइल को API को भेजता है, हर कुंजी, हर स्ट्रिंग, चाहे वह बदली हो या नहीं। एक छोटे प्रोजेक्ट के लिए शुरुआती दौर में यह ठीक है। एक परिपक्व प्रोजेक्ट के लिए जिसमें 10 या 20 भाषाओं में सैकड़ों अनुवाद कुंजियाँ हों, आप उन स्ट्रिंग्स पर टोकन बर्बाद कर रहे हैं जो पिछली बार से नहीं बदली हैं और इसके बदले समान आउटपुट प्राप्त कर रहे हैं।

डेल्टा अनुवाद इसे हल करता है। पूरे फाइल भेजने के बजाय, यह Action आपके वर्तमान स्रोत फाइल की तुलना एक संग्रहीत बेसलाइन से करता है, केवल उन कुंजियों की पहचान करता है जो जोड़ी गई या संशोधित हुई हैं, और केवल उन्हें API को भेजता है। अपरिवर्तित कुंजियों के लिए आउटपुट मौजूदा अनुवादित फाइलों से लिया जाता है। टोकन उपयोग वास्तविक किए गए काम के अनुरूप घट जाता है।

बेसलाइन कैसे काम करती है

जब डेल्टा मोड पहली बार चलता है, या जब आप पूर्ण रिफ्रेश को मजबूर करते हैं, तो Action पूरे स्रोत फाइल का अनुवाद करता है और इसे एक फ्लैट JSON प्रतिनिधित्व के रूप में आपके रिपॉजिटरी में बेसलाइन फाइल के रूप में संग्रहीत करता है। बाद के रन में, Action उस बेसलाइन को लोड करता है, इसे वर्तमान स्रोत फाइल से तुलना करता है, और केवल बदली हुई कुंजियों को शामिल करने वाला पेलोड बनाता है।

JSON लोकल फाइलों के लिए बेसलाइन को .polylingo-baseline.json के रूप में आपके messages डायरेक्टरी में संग्रहीत किया जाता है। YAML लोकल फाइलों के लिए यह .polylingo-yaml-baseline.json आपके locales डायरेक्टरी में होता है। Laravel PHP lang फाइलों के लिए यह .polylingo-laravel-php-baseline.json आपके lang डायरेक्टरी में होता है।

बेसलाइन आपके अनुवादित फाइलों के साथ कमिट की जाती है ताकि यह रिपॉजिटरी के साथ यात्रा करे। कोई भी डेवलपर जो रिपो क्लोन करता है, उसे वही बेसलाइन मिलती है जिस पर पाइपलाइन काम कर रही है।

क्या बदलाव माना जाता है

डिफ़ आपके स्रोत फाइल की फ्लैट की प्रतिनिधित्व पर काम करता है। नेस्टेड संरचनाएं तुलना से पहले डॉट-नोटेशन कुंजियों में फ्लैट की जाती हैं:

{
  "nav.home": "होम",
  "nav.about": "हमारे बारे में",
  "hero.title": "हमारे प्लेटफ़ॉर्म पर आपका स्वागत है",
  "hero.cta": "शुरू करें"
}

डेल्टा पेलोड में एक कुंजी शामिल की जाती है यदि:

यह वर्तमान स्रोत फाइल में है लेकिन बेसलाइन में नहीं (नई कुंजी)
यह दोनों में है लेकिन मान बदल गया है (संशोधित कुंजी)

जो कुंजियाँ बेसलाइन में हैं लेकिन वर्तमान स्रोत फाइल में नहीं (हटाई गई कुंजियाँ), उन्हें अनुवादित आउटपुट फाइलों से स्वचालित रूप से हटा दिया जाता है। जो कुंजियाँ दोनों में समान हैं, उन्हें पूरी तरह से छोड़ दिया जाता है और उनके मौजूदा अनुवाद वहीं रहते हैं।

व्यावहारिक रूप में यह कैसा दिखता है

मान लीजिए आपके पास Next.js प्रोजेक्ट है जिसमें messages/en.json में 200 अनुवाद कुंजियाँ हैं, जो पहले से ही 12 भाषाओं में अनुवादित हैं। एक डेवलपर हीरो सेक्शन की कॉपी अपडेट करता है और फीचर घोषणा के लिए दो नई कुंजियाँ जोड़ता है। यह 200 में से 4 बदली हुई कुंजियाँ हैं।

डेल्टा मोड के बिना, पाइपलाइन हर पुश पर 12 भाषाओं में गुणा करके सभी 200 कुंजियाँ भेजती है। डेल्टा मोड के साथ यह 4 कुंजियाँ भेजता है। उस रन के लिए टोकन उपयोग लगभग 2% है जो एक पूर्ण अनुवाद की लागत होती। पाइपलाइन भी तेज़ है क्योंकि भेजने और इंतजार करने के लिए कम है।

नियमित विकास के एक महीने में, बचत काफी बढ़ जाती है। अधिकांश पुश कुछ स्ट्रिंग्स को छूते हैं। पूर्ण पुनःअनुवाद केवल तब होता है जब आप नई भाषा जोड़ते हैं या स्पष्ट रूप से बेसलाइन रीसेट करते हैं।

तीन PolyLingo GitHub Actions

डेल्टा मोड सभी तीन PolyLingo अनुवाद Actions में उपलब्ध है। प्रत्येक एक विशिष्ट सामग्री प्रकार और प्रोजेक्ट संरचना के लिए बनाया गया है।

translateAction — JSON और Markdown

मूल Action। 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 — Marketplace पर देखें

translate-action-yaml — YAML लोकल फाइलें

नेस्टेड YAML लोकल फाइलों का उपयोग करने वाले प्रोजेक्ट्स के लिए: Rails i18n, Vue i18n, और कोई भी अन्य फ्रेमवर्क जो YAML फॉर्मेट का उपयोग करता है। Action Rails की रूट लोकल की की परंपरा को स्वचालित रूप से संभालता है — en.yml में en: रूट की होती है, और प्रत्येक आउटपुट फाइल को सही लक्ष्य लोकल की मिलती है (fr:, de: आदि)।

चूंकि PolyLingo API JSON के साथ मूल रूप से काम करता है, Action नेस्टेड 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 — Marketplace पर देखें

translate-action-laravel — Laravel lang फाइलें

Laravel प्रोजेक्ट्स के लिए जो JSON अनुवाद फाइलें (lang/en.json, Laravel 9+ शैली में नेस्टेड और फ्लैट दोनों संरचनाओं का समर्थन) या PHP एरे lang फाइलें (lang/en/*.php) उपयोग करते हैं। Action अपने आप पता लगाता है कि आपका प्रोजेक्ट कौन सा फॉर्मेट उपयोग करता है php_format: auto के माध्यम से — यह पहले lang/en.json की जांच करता है और न मिलने पर PHP एरे फाइलों पर वापस जाता है।

PHP फाइलों के लिए यह PHP CLI को कॉल करता है स्रोत फाइलें पढ़ने के लिए और अनुवादित आउटपुट को वैध PHP एरे सिंटैक्स में जावास्क्रिप्ट में सीरियलाइज़ करता है, बिना अतिरिक्त निर्भरताओं के। 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 — Marketplace पर देखें

PR मोड बनाम कमिट मोड

तीनों Actions दो आउटपुट मोड सपोर्ट करते हैं।

कमिट मोड (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

डाउनस्ट्रीम चरणों के लिए आउटपुट

तीनों Actions समान आउटपुट प्रदान करते हैं ताकि आप उन्हें बाद के वर्कफ़्लो चरणों में उपयोग कर सकें:

- 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: अनुवाद सांख्यिकी लॉग करें
  run: |
    echo "अनुवादित भाषाएँ: ${{ steps.translate.outputs.locales_translated }}"
    echo "बदले गए फाइल: ${{ steps.translate.outputs.files_changed }}"
    echo "उपयोग किए गए टोकन: ${{ steps.translate.outputs.tokens_used }}"

प्रत्येक रन GitHub Actions चरण सारांश में एक सारणी भी लिखता है ताकि आप टोकन उपयोग और अनुवाद परिणामों को लॉग्स में खोदे बिना देख सकें।

शुरू करना

तीनों Actions GitHub मार्केटप्लेस पर उपलब्ध हैं। आपको PolyLingo API कुंजी की आवश्यकता होगी, जो usepolylingo.com पर मुफ्त में उपलब्ध है। मुफ्त स्तर में प्रति माह 50,000 टोकन शामिल हैं। डेल्टा मोड सक्षम होने पर, अधिकांश प्रोजेक्ट नियमित विकास पुश पर इसके भीतर रहेंगे।

अपनी API कुंजी को रिपॉजिटरी सीक्रेट (POLYLINGO_API_KEY) के रूप में जोड़ें और संबंधित Action को अपने वर्कफ़्लो में डालें। पहला रन पूर्ण अनुवाद करता है और बेसलाइन सेट करता है। उसके बाद हर रन केवल बदले हुए हिस्सों का अनुवाद करता है।

आपको सब कुछ फिर से अनुवाद करने की आवश्यकता नहीं है: CI में डेल्टा अनुवाद कैसे काम करता है