Overview

This documentation explains how to integrate automated translation of localization files (.po and .json) using Azure AI Translator and a centralized GitHub Actions workflow. The system supports context-aware translations and generates automated PRs with translated content.

---

Powered by

• Azure Cognitive Services — Translator
• GitHub Actions for automation
• .po and .json localization files
• Support for gettext-style context handling (msgctxt, _x())

---

How It Works

Centralized Workflow

The parent workflow (newfold-labs/workflows/.github/workflows/auto-translate.yml) automates:

• Scanning .po and .json files
• Translating strings only if untranslated
• Respecting context from _x() or JSON keys like msgid|context
• Submitting a PR with the translated content

Child repositories only need a minimal dispatcher workflow.

---

Setup for Plugin/Module Repositories (Child)

1. Create Workflow in Your Plugin Repo

In .github/workflows/auto-translate.yml:

name: Auto Translate

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      text_domain:
        description: "Text domain (optional)"
        required: false
        default: ""

permissions:
  contents: write
  pull-requests: write

jobs:
  translate:
    uses: newfold-labs/workflows/.github/workflows/auto-translate.yml@main
    with:
      text_domain: $
    secrets:
      TRANSLATOR_API_KEY: $
      PERSONAL_ACCESS_TOKEN: $

---

2. Localization File Naming Convention

Ensure your translation files follow this pattern:

• .po files: my-plugin-textdomain-fr_FR-*.po, my-plugin-textdomain-es_ES-*.po, etc.

• .json files (e.g., for WordPress block editors): my-plugin-textdomain-fr_FR-*.json, etc.

The text domain must be included in the filename.

---

3. Use _x() or Context-Aware Keys

To support contextual translations, use:

• PHP:

  _x( 'Book', 'noun', 'my-plugin-textdomain' );
  _x( 'Book', 'verb', 'my-plugin-textdomain' );
  

• JSON message keys (gettext style):

  {
    "locale_data": {
      "messages": {
        "Save\u0004button": [""],
        "Save\u0004menu": [""]
      }
    }
  }
  

---

4. Translation Skips

The workflow skips:

• Any .po or .json entry that already has a translation
• Empty keys or metadata entries
• Malformed or non-standard entries

---

Secrets Required

Stored only in the central repo:

Secret Name	Purpose
TRANSLATOR_API_KEY	Azure Translator API key
PERSONAL_ACCESS_TOKEN	GitHub token with PR permissions

No need to store these secrets in child/plugin repos.

---

Pull Request Details

• Title: Auto-translated files update

• Body:

  This PR contains automatic translations of PO and JSON files using Azure AI Translator.
  Context-aware translations are handled for `_x()` and similar methods.
  

---

Tips for Plugin Developers

• Always extract strings using WordPress i18n functions: __(), _e(), _x(), etc.
• Use context where possible (_x()), especially for ambiguous terms.
• Organize translation files per locale and per text domain.
• Avoid duplicating strings with different whitespace or punctuation — they’ll be treated separately.

---

Workflow Triggers

• On every push to main (auto PR generated)
• On manual dispatch from the GitHub UI

---

Common Pitfalls

Mistake	Fix
File doesn’t include text domain	Rename file to follow pattern
_x() not used for context	Use _x() instead of __() where needed
No .po or .json files	Generate them using i18n tools like wp i18n make-pot