← Takaisin blogiin
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.

Sinun ei tarvitse kääntää kaikkea uudelleen: miten delta-käännös toimii CI:ssä

By Robert M

Sinun ei tarvitse kääntää kaikkea uudelleen: miten delta-käännös toimii CI:ssä

Kun olet liittänyt automaattisen käännöksen CI-putkeesi, luonnollinen kysymys nousee nopeasti: käännetäänkö koko paikallistiedosto uudelleen joka kerta, kun joku tekee muutoksen?

Ilman delta-tilaa, kyllä. Jokainen push, joka koskettaa lähdepaikallistiedostoa, lähettää koko tiedoston API:lle, jokaisen avaimen, jokaisen merkkijonon, muuttui se tai ei. Pienelle projektille alkuvaiheessa tämä on ok. Kypsälle projektille, jossa on satoja käännösavaimia 10 tai 20 kielellä, poltat tokeneita merkkijonoihin, jotka eivät ole muuttuneet viimeisestä ajosta, ja saat takaisin identtisen tuloksen tästä etuoikeudesta.

Delta-käännös ratkaisee tämän. Sen sijaan, että lähetettäisiin koko tiedosto, Action vertaa nykyistä lähdetiedostoasi tallennettuun vertailutiedostoon, tunnistaa vain lisätyt tai muokatut avaimet ja lähettää vain ne API:lle. Muuttumattomien avainten tulokset otetaan olemassa olevista käännetyistä tiedostoista. Tokenien käyttö laskee vastaamaan tehtyä työtä.

Miten vertailutiedosto toimii

Kun delta-tila ajetaan ensimmäistä kertaa tai kun pakotat täyden päivityksen, Action kääntää koko lähdetiedoston ja tallentaa siitä litteän JSON-esityksen vertailutiedostona repositorioon. Seuraavilla ajoilla Action lataa tämän vertailutiedoston, vertaa sitä nykyiseen lähdetiedostoon ja rakentaa kuorman, joka sisältää vain muuttuneet avaimet.

JSON-paikallistiedostoille vertailutiedosto tallennetaan nimellä .polylingo-baseline.json viestihakemistoon. YAML-paikallistiedostoille se on .polylingo-yaml-baseline.json paikallistiedostojen hakemistossa. Laravel PHP -kielitiedostoille se on .polylingo-laravel-php-baseline.json lang-hakemistossa.

Vertailutiedosto sitoutetaan käännettyjen tiedostojen rinnalle, joten se kulkee mukana repositoriossa. Jokainen kehittäjä, joka kloonaa repoon, saa saman vertailutiedoston, jota putki käyttää.

Mikä lasketaan muutokseksi

Diff toimii litteän avainesityksen perusteella lähdetiedostostasi. Sisäkkäiset rakenteet litistetään piste-notaatioksi ennen vertailua:

{
  "nav.home": "Koti",
  "nav.about": "Meistä",
  "hero.title": "Tervetuloa alustallemme",
  "hero.cta": "Aloita"
}

Avain sisällytetään delta-kuormaan, jos:

  • Se on nykyisessä lähdetiedostossa mutta ei vertailutiedostossa (uusi avain)
  • Se on molemmissa, mutta arvo on muuttunut (muokattu avain)

Avaimet, jotka ovat vertailutiedostossa mutta eivät nykyisessä lähdetiedostossa (poistetut avaimet), poistetaan automaattisesti käännetyistä tiedostoista. Avaimet, jotka ovat identtisiä molemmissa, ohitetaan kokonaan ja niiden olemassa olevat käännökset säilytetään.

Miltä tämä näyttää käytännössä

Oletetaan, että sinulla on Next.js-projekti, jossa on 200 käännösavainta tiedostossa messages/en.json, jo valmiiksi käännettynä 12 kielelle. Kehittäjä päivittää hero-osan tekstin ja lisää kaksi uutta avainta ominaisuustiedotteelle. Se on 4 muutettua avainta 200:sta.

Ilman delta-tilaa putki lähettää kaikki 200 avainta kerrottuna 12 kielellä jokaisella pushilla. Delta-tilassa se lähettää 4 avainta. Tokenien käyttö kyseisellä ajolla on noin 2 % siitä, mitä täysi käännös maksaisi. Putki on myös nopeampi, koska lähetettävää ja odotettavaa on vähemmän.

Kuukauden säännöllisen kehityksen aikana säästö kasautuu merkittävästi. Useimmat pushit koskettavat vain kourallista merkkijonoja. Täysi uudelleenkäännös tapahtuu vain, kun lisäät uuden kielen tai nollaat vertailutiedoston.

Kolme PolyLingo GitHub Actionia

Delta-tila on saatavilla kaikissa kolmessa PolyLingo-käännösactionissa. Jokainen on rakennettu tietylle sisältötyypille ja projektirakenteelle.

translateAction — JSON ja Markdown

Alkuperäinen Action. Käsittelee litteitä JSON-paikallistiedostoja next-intl- ja i18next-tyylillä, sisältäen valinnaisen Markdown-dokumentaatiokierroksen async jobs API:n kautta suuremmille tiedostoille.

- 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"

Delta-vertailutiedosto: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Katso Marketplace

translate-action-yaml — YAML-paikallistiedostot

Projekteille, jotka käyttävät sisäkkäisiä YAML-paikallistiedostoja: Rails i18n, Vue i18n ja muut YAML-muotoa käyttävät kehykset. Action käsittelee Railsin juuripaikallistiedoston avaimen automaattisesti — en.yml sisältää en:-juuriavaimen, ja jokainen tulostiedosto saa oikean kohdekieliavaimen (fr:, de: jne).

Koska PolyLingo API toimii natiivisti JSON:lla, Action litistää sisäkkäisen YAML:n piste-notaatioksi JSON:ksi ennen lähettämistä, kääntää ja rakentaa sitten rakenteen uudelleen ja kirjoittaa kelvollisen YAML-tulosteen. Yksi v1-varoitus: pisteitä sisältäviä avaimia ei tueta, koska ne ovat ristiriidassa piste-notaation litistämisen kanssa.

- 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

Delta-vertailutiedosto: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Katso Marketplace

translate-action-laravel — Laravel-kielitiedostot

Laravel-projekteille, jotka käyttävät joko JSON-käännöstiedostoja (lang/en.json, tukien sekä sisäkkäiset että litteät rakenteet Laravel 9+ -tyylillä) tai PHP-taulukko-kielitiedostoja (lang/en/*.php). Action tunnistaa automaattisesti käytetyn formaatin php_format: auto -asetuksella — se tarkistaa ensin lang/en.json ja käyttää PHP-taulukoita, jos JSON-tiedostoa ei löydy.

PHP-tiedostoille Action kutsuu PHP CLI:tä lukemaan lähdetiedostot ja sarjoittaa käännetyn tuloksen takaisin kelvolliseksi PHP-taulukoksi JavaScriptissä ilman lisäriippuvuuksia. GitHubin ubuntu-latest runnerit sisältävät oletuksena PHP 8.x:n, joten erillistä asennusvaihetta ei tarvita. PHP 7.4 tai uudempi vaaditaan.

Yksi v1-varoitus: pisteitä sisältäviä avaimia ei tueta PHP-tilassa piste-notaation litistämisen takia.

- 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

Delta-vertailutiedosto: lang/.polylingo-laravel-json-baseline.json tai lang/.polylingo-laravel-php-baseline.json formaatin mukaan.

github.com/UsePolyLingo/translate-action-laravel — Katso Marketplace

PR-tila vs commit-tila

Kaikki kolme Actionia tukevat kahta tulostustilaa.

Commit-tila (commit: true) kirjoittaa käännetyt tiedostot ja sitoo ne suoraan nykyiseen haaraan. Yksinkertainen asennus, hyvä tiimeille, jotka käsittelevät käännöksiä automatisoituna prosessina, joka ei tarvitse tarkistusta.

PR-tila (open_pr: true) luo uuden haaran (polylingo/yaml-<sha>, polylingo/laravel-<sha> jne), kirjoittaa käännetyt tiedostot sinne ja avaa pull requestin perushaaraa vastaan. Parempi tiimeille, jotka haluavat ihmisen tarkistuksen ennen käännetyn sisällön yhdistämistä, tai projekteille, joissa käännösten laatu vaikuttaa suoraan käyttäjäkokemukseen.

Kun molemmat on asetettu, PR-tila voittaa.

PR-tila vaatii pull-requests: write -oikeuden työnkulun käyttöoikeuksissa:

permissions:
  contents: write
  pull-requests: write

Täyden päivityksen pakottaminen

Delta-tila vertaa tallennettuun vertailutiedostoon. Jos haluat kääntää kaiken uudelleen riippumatta vertailutiedoston tilasta, aseta delta: false. Tämä myös päivittää vertailutiedoston vastaamaan nykyistä lähdetiedostoa, joten seuraavat delta-ajot alkavat uudesta tilasta.

Täysi päivitys on hyödyllinen, kun lisäät uuden kohdekielen, haluat hyödyntää käännösten laadun parannuksia uudessa malliversiossa tai kun vertailutiedosto on jostain syystä poikennut todellisuudesta.

- 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  # täysi päivitys, päivittää vertailutiedoston
    commit: true

Tulosteet seuraaville vaiheille

Kaikki kolme Actionia tarjoavat samat tulosteet, jotta voit käyttää niitä myöhemmissä työnkulun vaiheissa:

- 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: Kirjaa käännöstilastot
  run: |
    echo "Käännetyt kielet: ${{ steps.translate.outputs.locales_translated }}"
    echo "Muutetut tiedostot: ${{ steps.translate.outputs.files_changed }}"
    echo "Käytetyt tokenit: ${{ steps.translate.outputs.tokens_used }}"

Jokainen ajo kirjoittaa myös yhteenvedon GitHub Actions -vaiheen yhteenvetoon, jotta voit nähdä tokenien käytön ja käännöstulokset ilman lokien läpikäyntiä.

Aloittaminen

Kaikki kolme Actionia ovat saatavilla GitHub Marketplacessa. Tarvitset PolyLingo API-avaimen, joka on saatavilla ilmaiseksi osoitteessa usepolylingo.com. Ilmainen taso sisältää 50 000 tokenia kuukaudessa. Delta-tila päällä useimmat projektit pysyvät hyvin tämän rajan sisällä rutiininomaisissa kehityspuskuissa.

Lisää API-avaimesi repositorion salaisuudeksi (POLYLINGO_API_KEY) ja lisää sopiva Action työnkulkuusi. Ensimmäinen ajo tekee täyden käännöksen ja asettaa vertailutiedoston. Jokainen seuraava ajo kääntää vain muuttuneet kohdat.