Skip to main content

Συγχρονισμός αρχείων μετάφρασης: Διατηρήστε συγχρονισμένα τα κλειδιά i18n σε όλες τις γλώσσες

Κάθε φορά που ένας προγραμματιστής προσθέτει ένα κλειδί στη γλώσσα προέλευσης, άλλα 15 αρχεία γλωσσών παύουν να είναι συγχρονισμένα. Τα κλειδιά που λείπουν εμφανίζουν ανεπεξέργαστες διαδρομές στους χρήστες. Τα παρωχημένα κλειδιά σπαταλούν τον χρόνο των μεταφραστών και αυξάνουν το μέγεθος του bundle. Ο αυτοματοποιημένος συγχρονισμός διατηρεί τα πάντα ευθυγραμμισμένα.

1

Το πρόβλημα του συγχρονισμού

Τα αρχεία μετάφρασης αποκλίνουν συνεχώς μεταξύ τους. Ένας προγραμματιστής προσθέτει το «settings.notifications.title» στο en.json, αλλά ξεχνά να το προσθέσει στα υπόλοιπα 15 αρχεία γλωσσών. Ένας άλλος αφαιρεί το «onboarding.welcome» από τον κώδικα, αλλά το αφήνει σε όλα τα αρχεία γλωσσών. Ένας τρίτος μετονομάζει το «user.name» σε «user.displayName» στα Αγγλικά, αλλά όχι στις άλλες γλώσσες. Με την πάροδο των μηνών, τα αρχεία γλωσσών αποκλίνουν: κλειδιά λείπουν, παραμένουν παρωχημένα ή δεν αντιστοιχούν μεταξύ των γλωσσών.

The drift problem
// The problem: translation files drift out of sync

// Developer adds a new feature with new keys:
// en.json (source of truth)
{
  "nav.home": "Home",
  "nav.about": "About",
  "nav.pricing": "Pricing",     // NEW
  "nav.changelog": "Changelog"  // NEW
}

// de.json (out of sync - missing new keys)
{
  "nav.home": "Startseite",
  "nav.about": "Über uns"
  // nav.pricing - MISSING
  // nav.changelog - MISSING
}

// de.json also has stale keys from deleted features:
{
  "nav.home": "Startseite",
  "nav.about": "Über uns",
  "nav.legacy_page": "Alte Seite"  // STALE - removed from en.json
}
Τα κλειδιά που λείπουν είναι χειρότερα από τις μεταφράσεις που λείπουν. Όταν λείπει μια μετάφραση, μπορεί να χρησιμοποιηθεί εναλλακτικά η γλώσσα προέλευσης. Όταν λείπει ένα κλειδί, προκαλείται σφάλμα χρόνου εκτέλεσης, εμφανίζεται στον χρήστη η ανεπεξέργαστη διαδρομή του κλειδιού ή αποδίδεται κενή συμβολοσειρά. Ο συγχρονισμός πρέπει να επιβάλλεται και όχι να επαφίεται στην τύχη.
2

Εντοπισμός κλειδιών που λείπουν

Ένα κλειδί θεωρείται ότι λείπει, όταν υπάρχει στη γλώσσα προέλευσης αλλά όχι σε μια γλώσσα-στόχο. Πρόκειται για το συχνότερο και πιο επιζήμιο πρόβλημα συγχρονισμού — οι χρήστες βλέπουν ανεπεξέργαστες διαδρομές κλειδιών, όπως «settings.notifications.title», αντί για μεταφρασμένο κείμενο. Το i18n-validate εντοπίζει τα κλειδιά που λείπουν συγκρίνοντας τη δομή κλειδιών κάθε γλώσσας με εκείνη της γλώσσας προέλευσης.

Terminal
# Detect missing and stale keys
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json'

# Output:
# locales/de.json:
#   Missing keys (2):
#     - nav.pricing
#     - nav.changelog
#   Stale keys (1):
#     - nav.legacy_page
#   Coverage: 66.7% (2/3 keys)
#
# locales/ja.json:
#   Missing keys (5):
#     - nav.pricing
#     - nav.changelog
#     - settings.theme
#     - settings.language
#     - settings.notifications
#   Coverage: 50.0% (5/10 keys)
Εκτελέστε το i18n-validate με τη σημαία --check missing-keys, ώστε να εστιάσετε ειδικά στα προβλήματα συγχρονισμού. Χρησιμοποιήστε το --severity error, ώστε τα κλειδιά που λείπουν να προκαλούν αποτυχία στο CI και να διορθώνονται πριν από τη συγχώνευση.
3

Εντοπισμός παρωχημένων κλειδιών

Παρωχημένο κλειδί είναι ένα κλειδί που υπάρχει στα αρχεία μετάφρασης, αλλά δεν αναφέρεται πλέον στον κώδικα. Τα παρωχημένα κλειδιά σπαταλούν τον χρόνο των μεταφραστών, καθώς μεταφράζονται συμβολοσειρές που δεν βλέπει κανείς, αυξάνουν το μέγεθος του bundle και προκαλούν σύγχυση στη συντήρηση. Για τον εντοπισμό τους απαιτείται διασταύρωση των αρχείων γλωσσών με τις αναφορές στον κώδικα.

Terminal
# Step 1: Check which files are out of sync
npx i18n-validate sync --source locales/en.json --targets 'locales/*.json'

# Step 2: Auto-fill missing keys with source values (as placeholders)
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json' \
  --fill-missing \
  --fill-value "[NEEDS TRANSLATION] {{source}}"

# Step 3: Remove stale keys no longer in source
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json' \
  --remove-stale

# Step 4: Sort keys to match source order (cleaner diffs)
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json' \
  --sort-keys

# All at once:
npx i18n-validate sync \
  --source locales/en.json \
  --targets 'locales/*.json' \
  --fill-missing \
  --remove-stale \
  --sort-keys
4

Αυτοματοποίηση του συγχρονισμού

Η αποτελεσματικότερη στρατηγική συγχρονισμού συνδυάζει τρία επίπεδα: 1) Pre-commit hooks που επικυρώνουν τον συγχρονισμό σε κάθε commit. 2) Ελέγχους στο CI pipeline που εμποδίζουν συγχωνεύσεις με προβλήματα συγχρονισμού. 3) Περιοδικούς πλήρεις ελέγχους που εντοπίζουν αποκλίσεις συσσωρευμένες από επείγουσες διορθώσεις και μη αυτόματες αλλαγές.

.husky/pre-commit
# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Check if source locale file changed
SOURCE_CHANGED=$(git diff --cached --name-only | grep -c 'locales/en.json')

if [ "$SOURCE_CHANGED" -gt 0 ]; then
  echo "Source locale changed - checking sync..."

  npx i18n-validate sync \
    --source locales/en.json \
    --targets 'locales/*.json' \
    --fail-on-missing \
    --min-coverage 90

  if [ $? -ne 0 ]; then
    echo ""
    echo "Translation files are out of sync!"
    echo "Run: npx i18n-validate sync --fill-missing"
    exit 1
  fi
fi
.github/workflows/i18n-sync.yml
# .github/workflows/i18n-sync.yml
name: Translation Sync Check

on:
  pull_request:
    paths:
      - 'locales/**'

jobs:
  sync-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check translation sync
        run: npx i18n-validate sync \
          --source locales/en.json \
          --targets 'locales/*.json' \
          --fail-on-missing \
          --min-coverage 95

      - name: Comment on PR if out of sync
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: 'Translation files are out of sync. Please run npx i18n-validate sync --fill-missing and commit.'
            })
5

Αναφορές κάλυψης μεταφράσεων

Η κάλυψη μεταφράσεων είναι το ποσοστό των κλειδιών της γλώσσας προέλευσης που έχουν μεταφραστεί σε κάθε γλώσσα-στόχο. Το i18n-validate δημιουργεί μια αναφορά κάλυψης με ποσοστά ανά γλώσσα και επισημαίνει όσες υστερούν. Χρησιμοποιήστε όρια κάλυψης στο CI, ώστε να εμποδίζονται οι συγχωνεύσεις, όταν η κάλυψη πέφτει κάτω από ένα αποδεκτό επίπεδο.

Namespace-based sync
// Split large translation files by feature/namespace
// locales/
// ├── en/
// │   ├── common.json      (nav, footer, errors)
// │   ├── auth.json         (login, register, reset)
// │   ├── dashboard.json    (dashboard-specific)
// │   └── settings.json     (settings page)
// ├── de/
// │   ├── common.json
// │   ├── auth.json
// │   ├── dashboard.json
// │   └── settings.json

// Sync with namespace support:
npx i18n-validate sync \
  --source 'locales/en/*.json' \
  --targets 'locales/*/%.json' \
  --namespace-pattern '{locale}/{namespace}.json'

// Benefits:
// - Smaller files, easier to review
// - Feature teams own their translations
// - Lazy-load only needed namespaces
// - Parallel translation workflows
Ορίστε διαφορετικά όρια κάλυψης για κάθε γλώσσα. Οι κύριες γλώσσες σας (de, fr, ja) ενδέχεται να απαιτούν κάλυψη 100%, ενώ οι γλώσσες που προστέθηκαν πρόσφατα (th, vi) μπορούν να ξεκινούν από το 80% και το όριο να αυξάνεται σταδιακά.

Δοκιμάστε τώρα το i18n Agent

Αφήστε εδώ το αρχείο μετάφρασής σας

JSON, YAML, PO, XML, CSV, Markdown, Properties

ή κάντε κλικ για να επιλέξετε αρχείο

Γλώσσες-στόχοι

Δεν απαιτείται εγγραφήΆμεση εκτίμηση

Συχνές ερωτήσεις για τον συγχρονισμό αρχείων μετάφρασης