Supporting 2 or 3 languages? With Locawise, support virtually ALL languages for the price of a coffee! ☕

Locawise is your smart AI localization co-pilot, seamlessly integrated into your GitHub workflow. It automatically detects changes in your application's localization files, translates them using cutting-edge AI, and creates a pull request with the updates. Go global, effortlessly!

• Features
• How It Works
• Quick Start
  • Create Workflow File
  • Add Secrets
  • Enable Automatic PRs
  • Push to main
• Action Inputs
• Choosing Your LLM Provider
• Supported File Formats
• Behind The Scenes
• Contributing
• License

• 🚀 Automated & Effortless: Set it up once, and Locawise handles new translations whenever you push to your main branch. No more manual tracking or tedious copy-pasting!
• 🧠 Context-Aware AI Translations: Powered by OpenAI (GPT models) and Google Vertex AI (Gemini models), Locawise understands your application's context, glossary, and desired tone, delivering translations that are not just accurate but appropriate.
• 💰 Cost-Effective: Only new or changed text gets translated. Choose an efficient LLM provider like Gemini, and your costs can be close to zero!
• ⏱️ Lightning Fast: Localize thousands of keys in under a minute. Your time is valuable; spend it on coding, not translating.
• 🛠️ Developer-Friendly: Simple YAML configuration (i18n.yaml is generated by the action) lets you define everything from language codes to specific terminology directly in your workflow file.
• 🔄 Respects Your Edits: Manually refined a translation? Locawise's i18n.lock file ensures your specific changes are preserved and only new or source-language modifications trigger AI translation.
• 🔗 Flexible LLM Choice: Pick your preferred LLM provider and model.
• 💪 Built-in Resilience: Temporary LLM provider hiccups? Locawise implements exponential random backoff retries to overcome TPM (Tokens Per Minute) limits.
• 📂 Supports Your Format: Currently supports .json and .properties files, with more formats on the way!

The locawise-action leverages the locawise Python package.

1. It checks out your repository.
2. Sets up Python and installs locawise.
3. Dynamically creates an i18n.yaml configuration file based on your workflow inputs.
4. Runs locawise to:
   • Identify changes in your source language file using an i18n.lock file.
   • Translate only the new or modified keys into your target languages using the specified LLM, context, and glossary.
   • Update your target language files.
5. Commits the changes and creates a pull request for your review.

Get Locawise up and running in your project in minutes!

We provide several example workflows for different frameworks and LLM providers:

• React Applications

  • React with OpenAI - For React/Next.js apps using GPT models
  • React with Vertex AI - For React/Next.js apps using Gemini models

• Android Applications

  • Android with OpenAI - For Android apps using GPT models
  • Android with Vertex AI - For Android apps using Gemini models

• Spring Boot Applications

  • Spring Boot with OpenAI - For Java Spring Boot apps using GPT models
  • Spring Boot with Vertex AI - For Java Spring Boot apps using Gemini models

Each example contains specific configurations optimized for the framework and LLM provider combination.

Add a new workflow file to your repository (e.g., .github/workflows/localize.yml):

name: Localize Application Content

on:
  push:
    branches:
      - main # Or your default branch

permissions:
  contents: write
  pull-requests: write

jobs:
  localize:
    runs-on:  macos-latest
    steps:
      - name: Run Locawise Localization
        uses: aemresafak/locawise-action@v1 # Use the latest version
        with:
          # === Provider API Keys (Choose one) ===
          # openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          vertex-ai-service-account-key-base64: ${{ secrets.VERTEX_AI_SERVICE_ACCOUNT_KEY_BASE64 }} # Required if using Vertex AI

          # === Core Configuration ===
          source-lang-code: 'en'
          file-name-pattern: '{language}.json' # e.g., en.json, fr.json for React/Vue apps
                                             # or messages_{language}.properties for Java
          target-lang-codes: 'es,fr,de,it,tr,ja' # Comma-separated target languages
          localization-root-path: 'public/locales' # Path to your i18n files (e.g., public/locales, src/i18n)

          # === Context (Highly Recommended) ===
          context: |
            You are translating for "MyApp", a productivity application for creative professionals.
            Our users are designers, writers, and artists.
          glossary: |
            Project: A user's main workspace.
            Canvas: The area where users create their work.
            Export: The action of saving work to a file.

         tone: Be as polite as possible while also being friendly

          # === Optional: LLM Specifics ===
          # llm-model: 'gemini-1.5-flash' # e.g., 'gpt-4o', 'gemini-1.5-pro' (uses provider default if unset)
          llm-location: 'us-central1' # For Vertex AI

      - name: Get commit info
        id: commit-info
        run: |
          SHA_SHORT=$(git rev-parse --short HEAD)
          echo "sha_short=$SHA_SHORT" >> $GITHUB_OUTPUT
          COMMIT_MSG=$(git log -1 --pretty=%s | tr -d '\n')
          echo "commit_message=$COMMIT_MSG" >> $GITHUB_OUTPUT
        shell: bash

    # Feel free to change any part of the pull request!
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v7
        with:
          commit-message: "[Bot] Update localization files from commit ${{ steps.commit-info.outputs.sha_short }}"
          title: "[Bot] Localization Update (${{ steps.commit-info.outputs.sha_short }})"
          body: |
            🤖 This PR was automatically created by the locawise workflow.
            Localization files have been updated from commit ${{ steps.commit-info.outputs.sha_short }}.
            Original commit message: "${{ steps.commit-info.outputs.commit_message }}"
          branch: localization-${{ steps.commit-info.outputs.sha_short }}
          base: main # Or your default branch
          labels: automated-pr, bot, localization

• OpenAI: If using OpenAI, add your OpenAI API key as OPENAI_API_KEY in your repository's Settings > Secrets and variables > Actions.
• Vertex AI: If using Google Vertex AI:
  1. Create a Google Cloud service account with the "Vertex AI User" role (or more granular permissions as needed).
  2. Download the JSON key file for this service account.
  3. IMPORTANT: You MUST Base64 encode the entire content of this JSON key file.
     • On linux/macOS, you can use the terminal: cat /path/to/your-key-file.json | base64 -w 0 (the -w 0 flag prevents line wrapping).
     • On Windows, you can use PowerShell: [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((Get-Content -Path "/path/to/your-key-file.json" -Raw)))
     • Alternatively, use a trusted local Base64 encoding tool. Do not paste your key into untrusted online encoders.
  4. Add the resulting Base64 encoded string as VERTEX_AI_SERVICE_ACCOUNT_KEY_BASE64 in your repository's Settings > Secrets and variables > Actions.

1. Enable GitHub Actions to Create PRs: Some repositories may need to explicitly enable GitHub Actions to create pull requests. You can do this in your repository's Settings → Actions → General → Workflow permissions, and ensure "Allow GitHub Actions to create and approve pull requests" is checked.

Make a change to your source language file (e.g., public/locales/en.json) and push to your main branch. Locawise will automatically run, translate, and create a PR!

Here's a detailed breakdown of the inputs for locawise-action:

Locawise supports:

• OpenAI: Access to powerful models like GPT-4o, GPT-4, GPT-3.5-turbo. Requires an OPENAI_API_KEY.
• Google Vertex AI: Access to efficient and capable models like Gemini (e.g., gemini-1.5-flash, gemini-1.5-pro). Requires a VERTEX_AI_SERVICE_ACCOUNT_KEY_BASE64 (the Base64 encoded JSON service account key).

You can provide secrets for the provider that you want to use.

• ✅ .json (key-value, including nested objects; commonly used with {language}.json naming)
• ✅ .properties (Java properties files; commonly used with messages_{language}.properties naming)
• ✅ .xml (Android strings.xml files; commonly used with values-{language}/strings.xml)
• 🔜 More formats coming soon! The architecture is designed for easy expansion.

Want to understand how Locawise works under the hood? Visit the main Locawise Python package repository at https://github.com/aemresafak/locawise to learn about the core implementation, contribute to the underlying functionality, or report issues with the translation engine itself. This action uses locawise 1.3.1.

Contributions are welcome! Whether it's bug reports, feature requests, or pull requests, please feel free to contribute to making Locawise even better.

This project is licensed under the MIT License.

Made with ❤️ by aemresafak