← Rudi kwenye blogu
A git diff view showing a locale file with three changed keys highlighted, and only those three keys being sent to the translation API below.

Huna haja ya kutafsiri kila kitu tena: jinsi tafsiri ya delta inavyofanya kazi katika CI

By Robert M

Huna haja ya kutafsiri kila kitu tena: jinsi tafsiri ya delta inavyofanya kazi katika CI

Mara tu unapokuwa na tafsiri ya moja kwa moja imeunganishwa kwenye mchakato wako wa CI, swali la kawaida linaibuka haraka: je, hii inatafsiri faili nzima ya eneo kila wakati mtu anapofanya push?

Bila hali ya delta, ndiyo. Kila push inayogusa faili lako la chanzo la eneo hutuma faili lote kwa API, kila ufunguo, kila mfuatano, iwe umebadilika au la. Kwa mradi mdogo mwanzoni, hiyo ni sawa. Kwa mradi mzuri wenye mamia ya funguo za tafsiri katika lugha 10 au 20, unatumia tokeni kwa mfuatano ambao haujabadilika tangu mara ya mwisho na unapata matokeo sawa kwa heshima hiyo.

Tafsiri ya delta inatatua hili. Badala ya kutuma faili kamili, Action inalinganisha faili lako la chanzo la sasa dhidi ya msingi ulihifadhiwa, hutambua funguo tu zilizoongezwa au zilizobadilishwa, na hutuma hizo tu kwa API. Matokeo kwa funguo zisizobadilika huchukuliwa kutoka kwa faili zilizotafsiriwa zilizopo. Matumizi ya tokeni hupungua ili kuendana na kazi halisi inayofanywa.

Jinsi msingi unavyofanya kazi

Wakati hali ya delta inapoendesha kwa mara ya kwanza, au unapobadilisha upya kikamilifu, Action hutafsiri faili kamili la chanzo na kuhifadhi uwakilishi wa JSON uliofanywa usawa kama faili la msingi katika hifadhi yako. Katika mara zinazofuata, Action huchukua msingi huo, hulinganisha na faili la chanzo la sasa, na kujenga mzigo unaojumuisha funguo zilizobadilika tu.

Kwa faili za eneo za JSON, msingi huhifadhiwa kama .polylingo-baseline.json katika saraka yako ya ujumbe. Kwa faili za eneo za YAML ni .polylingo-yaml-baseline.json katika saraka yako ya maeneo. Kwa faili za Laravel PHP lang ni .polylingo-laravel-php-baseline.json katika saraka yako ya lang.

Msingi unahifadhiwa pamoja na faili zako zilizotafsiriwa ili usafiri pamoja na hifadhi. Mwanaendelezaji yeyote anayekopa repo anapata msingi uleule ambao pipeline inafanya kazi nao.

Nini kinahesabiwa kama mabadiliko

Tofauti hufanya kazi kwenye uwakilishi wa funguo uliofanywa usawa wa faili lako la chanzo. Miundo iliyojificha hufanywa usawa kuwa funguo za noti ya nukta kabla ya kulinganisha:

{
  "nav.home": "Nyumbani",
  "nav.about": "Kuhusu sisi",
  "hero.title": "Karibu kwenye jukwaa letu",
  "hero.cta": "Anza sasa"
}

Ufunguo unajumuishwa katika mzigo wa delta ikiwa:

  • Upatikana katika faili la chanzo la sasa lakini haupo katika msingi (ufunguo mpya)
  • Upatikana katika zote mbili lakini thamani imebadilika (ufunguo uliobadilishwa) Funguo zinazopatikana katika msingi lakini si katika faili la chanzo la sasa (funguo zilizofutwa) zinaondolewa moja kwa moja kutoka kwa faili za matokeo yaliyotafsiriwa. Funguo zinazofanana katika zote mbili hupitishwa kabisa na tafsiri zao zilizopo huachwa mahali pake.

Hii inaonekanaje katika vitendo

Sema una mradi wa Next.js wenye funguo 200 za tafsiri katika messages/en.json, tayari kutafsiriwa katika lugha 12. Mwanaendelezaji anasasisha nakala ya sehemu ya hero na kuongeza funguo mbili mpya kwa tangazo la kipengele. Hizo ni funguo 4 zilizobadilika kati ya 200.

Bila hali ya delta, pipeline hutuma funguo zote 200 zikiwa zimezidishwa kwa lugha 12 kila push. Kwa hali ya delta hutuma funguo 4. Matumizi ya tokeni kwa mzunguko huo ni takriban 2% ya gharama ya tafsiri kamili. Pipeline pia ni haraka zaidi kwa sababu kuna kidogo cha kutuma na kidogo cha kusubiri.

Katika mwezi wa maendeleo ya kawaida, akiba huongezeka sana. Push nyingi hugusa mfuatano kidogo. Tafsiri kamili hupatikana tu unapoongeza lugha mpya au kwa wazi kurekebisha msingi.

PolyLingo GitHub Actions tatu

Hali ya delta inapatikana katika Actions zote tatu za tafsiri za PolyLingo. Kila moja imejengwa kwa aina maalum ya maudhui na muundo wa mradi.

translateAction — JSON na Markdown

Action ya asili. Inashughulikia faili za eneo za JSON zilizo sawa katika mtindo wa next-intl na i18next, na upitishaji wa nyaraka wa Markdown kupitia API ya kazi za async kwa faili kubwa.

- 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): sinkroniza tafsiri"

Msingi wa delta: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Tazama kwenye Marketplace

translate-action-yaml — faili za eneo za YAML

Kwa miradi inayotumia faili za eneo za YAML zilizo na muundo wa ndani: Rails i18n, Vue i18n, na fremu nyingine yoyote inayotumia muundo wa YAML. Action inashughulikia kanuni ya Rails ya ufunguo wa mzizi wa eneo moja kwa moja — en.yml ina ufunguo wa mzizi en:, na kila faili ya matokeo hupata ufunguo sahihi wa lugha lengwa (fr:, de: n.k).

Kwa kuwa API ya PolyLingo inafanya kazi na JSON asili, Action hufanya flatten ya YAML iliyojificha hadi JSON ya noti ya nukta kabla ya kutuma, kutafsiri, kisha kujenga upya muundo wa ndani na kuandika matokeo halali ya YAML. Kitu kimoja cha tahadhari cha v1 cha kujua: funguo zinazojumuisha nukta asili hazitumiwi, kwa sababu zinapingana na mkakati wa flatten wa noti ya nukta.

- 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

Msingi wa delta: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Tazama kwenye Marketplace

translate-action-laravel — faili za lang za Laravel

Kwa miradi ya Laravel inayotumia faili za tafsiri za JSON (lang/en.json, zinazounga mkono miundo ya ndani na ya usawa katika mtindo wa Laravel 9+) au faili za PHP array lang (lang/en/*.php). Action hutambua moja kwa moja ni muundo gani mradi wako unatumia kupitia php_format: auto — inatafuta lang/en.json kwanza na inarudi kwa faili za PHP array ikiwa haipatikani.

Kwa faili za PHP, inaitisha CLI ya PHP kusoma faili za chanzo na kusafirisha matokeo yaliyotafsiriwa kurudi kwa sintaksia halali ya array ya PHP katika JavaScript, bila utegemezi wa ziada. Runners wa GitHub walioko ubuntu-latest hujumuisha PHP 8.x kwa chaguo-msingi hivyo hakuna hatua ya ziada ya usanidi inahitajika. PHP 7.4 au zaidi inahitajika.

Tahadhari moja ya v1: funguo zinazojumuisha nukta hazitumiwi katika hali ya PHP kutokana na mkakati wa flatten wa noti ya nukta.

- 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

Msingi wa delta: lang/.polylingo-laravel-json-baseline.json au lang/.polylingo-laravel-php-baseline.json kulingana na muundo.

github.com/UsePolyLingo/translate-action-laravel — Tazama kwenye Marketplace

Hali ya PR dhidi ya hali ya commit

Actions zote tatu zinaunga mkono hali mbili za matokeo.

Hali ya commit (commit: true) huandika faili zilizotafsiriwa na kuzi-commit moja kwa moja kwenye tawi la sasa. Usanidi rahisi, mzuri kwa timu zinazotumia tafsiri kama mchakato wa moja kwa moja usiohitaji ukaguzi.

Hali ya PR (open_pr: true) huunda tawi jipya (polylingo/yaml-<sha>, polylingo/laravel-<sha> n.k), huandika faili zilizotafsiriwa huko, na hufungua pull request dhidi ya tawi lako la msingi. Bora kwa timu zinazotaka hatua ya ukaguzi wa binadamu kabla ya maudhui yaliyotafsiriwa kuunganishwa, au kwa miradi ambapo ubora wa tafsiri unaathiri moja kwa moja uzoefu wa mtumiaji.

Wakati zote mbili zimetangazwa, hali ya PR hushinda.

Hali ya PR inahitaji pull-requests: write katika ruhusa za workflow yako:

permissions:
  contents: write
  pull-requests: write

Kulazimisha upya kamili

Hali ya delta inalinganisha dhidi ya msingi ulihifadhiwa. Ikiwa unataka kutafsiri tena kila kitu bila kujali kile msingi unaonyesha, weka delta: false. Hii pia inasasisha msingi ili ulingane na faili la chanzo la sasa, hivyo mizunguko inayofuata ya delta huanza kutoka hali mpya.

Upya kamili ni muhimu unapoongeza lugha mpya lengwa, unapotaka kupata maboresho ya ubora wa tafsiri katika toleo jipya la mfano, au wakati msingi umeelekea mbali na ukweli kwa sababu yoyote.

- 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  # upya kamili, unasasisha msingi
    commit: true

Matokeo kwa hatua zinazofuata

Actions zote tatu zinaonyesha matokeo sawa ili uweze kuyatumia katika hatua za workflow zinazofuata:

- 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: Andika takwimu za tafsiri
  run: |
    echo "Lugha zilizotafsiriwa: ${{ steps.translate.outputs.locales_translated }}"
    echo "Faili zilizobadilika: ${{ steps.translate.outputs.files_changed }}"
    echo "Tokeni zilizotumika: ${{ steps.translate.outputs.tokens_used }}"

Kila mzunguko pia huandika jedwali la muhtasari kwenye muhtasari wa hatua ya GitHub Actions ili uweze kuona matumizi ya tokeni na matokeo ya tafsiri bila kuchimba kupitia kumbukumbu.

Kuanzisha

Actions zote tatu zinapatikana kwenye GitHub Marketplace. Utahitaji ufunguo wa API wa PolyLingo, unaopatikana bure kwenye usepolylingo.com. Kiwango cha bure kinajumuisha tokeni 50,000 kwa mwezi. Ukiwa na hali ya delta imewezeshwa, miradi mingi itaendelea vizuri ndani ya hiyo kwa pushes za maendeleo ya kawaida.

Ongeza ufunguo wako wa API kama siri ya hifadhi (POLYLINGO_API_KEY) na weka Action husika kwenye workflow yako. Mzunguko wa kwanza hufanya tafsiri kamili na kuweka msingi. Kila mzunguko baada ya huo hutafsiri tu kile kilichobadilika.