Översättningar i Ruby on Rails

Localhero.ai översätter YAML-filer för Rails i18n vid varje pull request. När du lägger till nycklar i config/locales översätter GitHub-actionen nya nycklar och nycklar som saknar översättning och committar de uppdaterade språkfilerna till samma PR. Då får du översättningar som följer ditt varumärke, redo att driftsättas tillsammans med resten av ändringarna.

Förutsättningar

En Rails-app med språkfiler i config/locales/
Node 18 eller senare för att köra CLI:t via npx
En API-nyckel för Localhero.ai

Hämta en API-nyckel från ditt konto.

Konfiguration

1. Sätt upp projektet

Kör CLI:t i projektmappen. Du behöver inte installera något. CLI:t känner igen Rails-mappstrukturen och föreslår rätt konfiguration:

npx @localheroai/cli init

CLI:t kommer föreslå att använda config/locales/ med mönstret **/*.{yml,yaml} och frågar sedan vilket källspråk och vilka målspråk du använder.

2. Kontrollera den genererade konfigurationen

init skriver en localhero.json i projektmappen. Så här kan konfigurationen se ut:

localhero.json

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

Committa den här filen. Fälten är dokumenterade i Projektkonfiguration.

3. Lägg till ett GitHub Actions-workflow

init kommer fråga om det ska skapa en GitHub Action-workflowfil för Localhero.ai. För att det ska fungera behöver du lägga till API-nyckeln på GitHub som en repository secret med namnet LOCALHERO_API_KEY, så översätts nya nycklar vid varje pull request. Workflowet använder localheroai/localhero-action.

Om du vill skapa det manuellt använder du filen nedan, där filtret paths: är begränsat till 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 behövs eftersom actionen diffar mot bas-branchen. Vid en shallow checkout finns ingen historik att jämföra med. Alla inputs beskrivs i guiden för GitHub Actions.

Så fungerar det

Du öppnar en pull request som lägger till eller ändrar nycklar i källspråkets språkfil, till exempel config/locales/en.yml.
GitHub-actionen diffar den aktuella branchen mot bas-branchen och översätter bara nycklar som har ändrats eller saknar översättning. Uppdaterade och borttagna nycklar synkas till Localhero backend, så att webbgränssnittet fortsätter att stämma överens med kodbasen och dina pull requests.
Actionen committar de uppdaterade YAML-filerna till samma PR. Diffen du granskar innehåller då både kod och översättningar.
När actionen har körts läggs en kommentar till på pull requesten med en länk till Localhero.ai för granskning och enkel justering. Du granskar och redigerar översättningarna i dashboarden, och ändringarna synkas tillbaka till branchen.

Appen behöver inte känna till Localhero.ai. Språkfilen i YAML-format är hela integrationen, så dina I18n.t-anrop och din vykod kan vara oförändrade.

Vill du inte översätta automatiskt i pull requests? Hoppa över actionen och kör npx @localheroai/cli translate lokalt för att översätta alla nycklar som saknar översättning. Committa sedan resultatet själv. Se CLI-referensen.

En längre genomgång med en riktig kodbas: att lokalisera en Ruby on Rails-app.

Specifikt för Rails

Uppdelade och nästlade språkfiler

Språkfiler som är uppdelade efter område, till exempel devise.en.yml eller en/models.yml, fungerar utan extra konfiguration. Mönstret **/*.{yml,yaml} är rekursivt. Språkkoden hämtas i följande ordning: filens basnamn, ett sökvägssegment, ett suffix efter _ eller -, och slutligen den överliggande mappen.

Språkkoden måste ha formatet xx eller xx-XX, med gemener i språkdelen. För andra format anger du translationFiles.localeRegex.

Nycklar du aldrig vill ha översatta

Använd ignoreKeys för interna strängar som inte ska översättas. Värdet kan innehålla exakta nycklar eller ett avslutande wildcard och används av både translate och push:

localhero.json (utdrag)

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

Vill du hoppa över hela filer i stället för enskilda nycklar använder du ignore med ett glob-mönster.

Byta namn på och ta bort nycklar

I flödet för pull requests sköts det automatiskt: nycklar som tas bort i diffen rapporteras till backend tillsammans med övriga ändringar. Det manuella kommandot push är försiktigare och tar aldrig bort något. Om du har döpt om eller tagit bort nycklar utanför en pull request kör du push --prune --force för att synka backend med dina filer.

Pluralformer

Varje målspråk får sina egna CLDR-pluralkategorier i stället för en kopia av kategorierna i källspråket. Ett språk som polska får till exempel extra pluralformer även om det engelska källspråket bara använder one och other.

En fil med flera språk

Allt ovan förutsätter ett språk per fil. Om dina YAML-filer i stället innehåller flera språk som toppnivånycklar aktiverar du translationFiles.multiLanguageFiles. Funktionen är i beta och stöder bara YAML och JSON. En fil räknas som flerspråkig när alla toppnivånycklar är konfigurerade språk och minst två språk finns med.

Vanliga frågor

Kan jag översätta vissa språk själv?

Ja. Stäng av automatisk översättning för varje språk du vill hantera själv. Då skriver Localhero.ai inga översättningar till språkfilen. CLI:t visar att språken hoppades över, och du hanterar dem i ditt eget flöde medan övriga språk översätts automatiskt.

Översätts hela språkfilen vid varje pull request?

Nej, bara nycklar som har ändrats eller saknar översättning. För pull requests jämförs diffen med bas-branchen. Lokalt jämför --changed-only med main, om du inte har angett en annan branch i translationFiles.baseBranch.

Hur hindrar jag actionen från att köras för en viss PR?

Lägg till labeln skip-translation. Actionen hoppar också över draft-PR:er och commits som den själv har skapat. Läs mer i guiden för GitHub Actions.

Ruby on Rails