Oversettelser i Ruby on Rails

Localhero.ai oversetter YAML-filer for Rails i18n ved hver pull request. Når du legger til oversettelsesnøkler i config/locales, oversetter GitHub-actionen de nye nøklene og fyller inn oversettelser som mangler. Deretter committer den de oppdaterte språkfilene til samme PR. Dermed får du oversettelser som er i tråd med merkevaren din og klare til å driftsettes sammen med resten av endringene.

Forutsetninger

En Rails-app med språkfiler i config/locales/
Node 18 eller nyere for å kjøre CLI-et via npx
En API-nøkkel for Localhero.ai

Hent en API-nøkkel fra kontoen din.

Oppsett

1. Sett opp prosjektet

Kjør CLI-et i prosjektets rotmappe. Du trenger ikke å installere noe. CLI-et kjenner igjen Rails-mappestrukturen og foreslår riktig konfigurasjon:

npx @localheroai/cli init

CLI-et foreslår config/locales/ med mønsteret **/*.{yml,yaml} og spør deretter hvilket kildespråk og hvilke målspråk du bruker.

2. Sjekk den genererte konfigurasjonen

init oppretter localhero.json i prosjektets rotmappe. Konfigurasjonen kan se slik ut:

localhero.json

{
  "schemaVersion": "1.0",
  "projectId": "your-project-id",
  "sourceLocale": "en",
  "outputLocales": ["sv", "nb", "de", "es"],
  "translationFiles": {
    "paths": ["config/locales/"],
    "pattern": "**/*.{yml,yaml}"
  }
}

Committ denne filen. Feltene er dokumentert i Prosjektoppsett.

3. Legg til en GitHub Actions-arbeidsflyt

init spør om du vil opprette en GitHub Actions-arbeidsflyt for Localhero.ai. For at den skal fungere, legger du til API-nøkkelen som en repository secret på GitHub med navnet LOCALHERO_API_KEY. Da oversettes nye oversettelsesnøkler ved hver pull request. Arbeidsflyten bruker localheroai/localhero-action.

Hvis du vil sette opp arbeidsflyten manuelt, bruker du filen nedenfor. Her er paths:-filteret begrenset til config/locales/:

.github/workflows/localhero-translate.yml

name: Localhero.ai - Automatic I18n translation

on:
  pull_request:
    paths:
      - "config/locales/**"
      - "localhero.json"
  repository_dispatch:
    types: [localhero-sync]
  workflow_dispatch:

concurrency:
  group: translate-${{ github.event.client_payload.branch || github.head_ref || github.run_id }}
  cancel-in-progress: true

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.client_payload.branch || github.head_ref || github.ref_name }}
          fetch-depth: 0

      - uses: localheroai/localhero-action@v1
        with:
          api-key: ${{ secrets.LOCALHERO_API_KEY }}

fetch-depth: 0 trengs fordi actionen sammenligner mot bas-branchen. En shallow checkout har ingen historikk å sammenligne med. Du finner alle parametrene i guiden for GitHub Actions.

Slik fungerer det

Du åpner en pull request som legger til eller endrer oversettelsesnøkler i språkfilen for kildespråket, for eksempel config/locales/en.yml.
GitHub-actionen sammenligner den aktuelle branchen med bas-branchen og oversetter bare nøkler som er endret eller mangler oversettelse. Oppdaterte og fjernede nøkler synkroniseres til Localhero backend, slik at nettgrensesnittet holder seg i tråd med kodebasen og pull requestene dine.
Actionen committer de oppdaterte YAML-filene til samme PR. Diffen du går gjennom, inneholder da både kode og oversettelser.
Når actionen er ferdig, legger den igjen en kommentar i pull requesten med en lenke til Localhero.ai. Der går du gjennom og redigerer oversettelsene, og endringene synkroniseres tilbake til branchen.

Appen din trenger ikke å vite at Localhero.ai finnes. YAML-språkfilen er hele integrasjonen, så I18n.t-kallene og view-koden kan være uendret.

Vil du ikke oversette automatisk i pull requests? Hopp over actionen og kjør npx @localheroai/cli translate lokalt for å oversette alle nøkler som mangler oversettelse. Committ deretter resultatet selv. Se CLI-referansen.

En lengre gjennomgang med en reell kodebase: slik lokaliserer du en Ruby on Rails-app.

Spesifikt for Rails

Delte og nøstede språkfiler

Språkfiler som er delt opp etter område, for eksempel devise.en.yml eller en/models.yml, fungerer uten ekstra konfigurasjon. Mønsteret **/*.{yml,yaml} er rekursivt. Språkkoden hentes i denne rekkefølgen: filens basenavn, et stisegment, et suffiks etter _ eller -, og til slutt den overliggende mappen.

Språkkoden må ha formatet xx eller xx-XX, med små bokstaver i språkdelen. For andre formater setter du translationFiles.localeRegex.

Oversettelsesnøkler du ikke vil oversette

Bruk ignoreKeys for intern tekst som ikke skal oversettes. Du kan angi eksakte oversettelsesnøkler eller bruke jokertegn på slutten. Innstillingen gjelder både translate og push:

localhero.json (utdrag)

"translationFiles": {
  "paths": ["config/locales/"],
  "pattern": "**/*.{yml,yaml}",
  "ignoreKeys": ["admin.*", "internal.debug_banner"]
}

Vil du hoppe over hele filer i stedet for enkeltnøkler, bruker du ignore med et glob-mønster.

Endre navn på eller fjerne oversettelsesnøkler

I pull request-flyten skjer dette automatisk: Nøkler som fjernes i diffen, rapporteres til backend sammen med resten av endringene. Den manuelle push-kommandoen fjerner derimot ikke nøkler med mindre du bruker --prune. Har du gitt nytt navn til eller fjernet nøkler utenfor en pull request, kjører du push --prune --force for å synkronisere backend med filene dine.

Pluralformer

Hvert målspråk får sine egne CLDR-pluralkategorier i stedet for en kopi av kategoriene i kildespråket. For eksempel får polsk ekstra pluralformer selv om det engelske kildespråket bare bruker one og other.

Én fil med flere språk

Alt ovenfor forutsetter ett språk per fil. Hvis YAML-filene dine i stedet inneholder flere språk under hver sin toppnivånøkkel, slår du på translationFiles.multiLanguageFiles. Funksjonen er i beta og støtter bare YAML og JSON. En fil regnes som flerspråklig når hver toppnivånøkkel er en konfigurert språkkode, og filen inneholder minst to språk.

Vanlige spørsmål

Kan jeg oversette enkelte språk selv?

Ja. Slå av automatisk oversettelse for hvert språk du vil håndtere selv. Da skriver Localhero.ai ingen oversettelser til språkfilen for det språket. CLI-et viser hvilke språk som hoppes over, og du håndterer dem i din egen arbeidsflyt mens resten oversettes automatisk.

Blir hele språkfilen oversatt ved hver pull request?

Nei, bare oversettelsesnøkler som er endret eller mangler oversettelse. I en pull request sammenligner actionen den aktuelle branchen med bas-branchen. Lokalt sammenligner --changed-only med main, med mindre du har angitt en annen branch i translationFiles.baseBranch.

Hvordan hindrer jeg actionen i å kjøre for en bestemt PR?

Legg til labelen skip-translation. Actionen hopper også over draft-PR-er og sine egne commits. Detaljene finner du i guiden for GitHub Actions.

Ruby on Rails