Android Resource Translator

Android Resource Translator scans strings.xml files for missing translations and automatically translates them using modern LLM providers.

GitHub Actions Workflow Examples

Simple Example (Using OpenRouter with Gemini - Default)

If you want to quickly try out the action with minimal configuration, add this step to your workflow. This uses the default provider (OpenRouter) and model (Gemini google/gemini-2.5-flash):

- name: Run Android Resource Translator
  uses: duartebarbosadev/AndroidResourceTranslator@v3
  env:
    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

Simple Example (Using OpenAI)

- name: Run Android Resource Translator
  uses: duartebarbosadev/AndroidResourceTranslator@v3
  with:
    llm_provider: openai
    model: gpt-4o-mini
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Advanced Workflow Example

For a more complete setup—including checking out your repository, running the translator with additional options, and automatically creating a pull request with the translation report—use the following workflow snippet:

name: Auto-translate strings.xml

on:
  push:
    branches:
      - main
    paths:
      - '**/values/strings.xml' # Call only when strings.xml is updated
  workflow_dispatch:
    
permissions:
  contents: write
  pull-requests: write

concurrency:
  group: "${{ github.workflow }}-${{ github.ref }}"
  cancel-in-progress: true

jobs:
  perform-auto-translate:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v6

      - name: Translate strings.xml to supported languages
        id: translate
        uses: duartebarbosadev/AndroidResourceTranslator@v3
        #with: # (Optional inputs - see readme for default values)
          #llm_provider: openrouter
          #model: google/gemini-2.5-flash
          #resources_paths: "./app/src/main/res"  # default with no value will search throughout the project automatically
          #log_trace: "true" # default is false
          #ignore_folders: "build" # Default will follow .gitignore
          #project_context: "Your project context here" # (Default is no context)
          #openrouter_send_site_info: "false" # Set to false to disable sending site info to OpenRouter
          #include_reference_context: "false" # Disable sharing existing translations as prompt context
          #reference_context_limit: "10" # Reduce or increase how many examples are sent
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

      - name: Save translation report for PR body
        run: |
          cat <<'EOF' > "${{ runner.temp }}/translation_report.md"
          ${{ steps.translate.outputs.translation_report }}
          EOF

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v8
        with:
          branch: auto-translate  # Use a fixed branch name
          commit-message: "[Translate Bot] Auto-generated translations for non-English languages"
          committer: "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
          author: "${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>"
          signoff: "false"
          title: "[Translate Bot] Auto-generated translations for non-English languages"
          body-path: ${{ runner.temp }}/translation_report.md
          labels: "translation, automated pr"
          assignees: "[yourname]"
          reviewers: "[yourname]"

⚠️ Warning ⚠️ If you don’t specify a model, the action will use this project’s default model, which may change in future releases to improve translation quality but cost might change.

⚠️ API Usage and Pricing Considerations

Please note that each time the action runs, it will process all missing translations. This can impact your API usage and associated costs, especially for large projects with many strings or frequent commits. Meaning that you should accept this action PR's as soon as possible to avoid repeating runs.

We recommend the model google/gemini-2.5-flash as it got the best results in our testing and is not as expensive as other models.

Supported LLM Providers & Models (via LiteLLM)

Thanks to the integration of LiteLLM, this tool natively supports 100+ LLM providers. You can check the LiteLLM repository and their providers documentation to see the full list of supported models and setup guides.

1. Direct API Providers

Specify the llm_provider and model in your inputs, and supply the corresponding API key as a repository secret:

• Anthropic Claude:
  • llm_provider: anthropic
  • model: claude-3-5-sonnet-latest
  • Environment variable: ANTHROPIC_API_KEY
• Google Gemini (Direct API):
  • llm_provider: gemini
  • model: gemini/gemini-2.5-flash (or gemini/gemini-2.5-pro)
  • Environment variable: GEMINI_API_KEY
• Azure OpenAI:
  • llm_provider: azure
  • Environment variables: standard Azure keys (AZURE_API_KEY, AZURE_API_BASE, etc.)

2. Local / Offline Translation (Free & Private)

You can run models locally using Ollama:

• Ollama:
  • llm_provider: ollama
  • model: ollama/llama3

Local Execution

To run the translator on your local machine, execute:

python app/AndroidResourceTranslator.py /path/to/your/android/project

You can also pass additional parameters like --api-key, --project-context, or --dry-run (to only check for missing translations without translating) as needed.

Configuration

The action supports the following inputs:

Input	Description	Default Value	Optional	Example
resources_paths	Paths to the Android resource directories. Typically includes directories such as app/src/main/res, library/src/main/res, etc. If not provided, this action will search throughout the entire project folder.	${{ github.workspace }}	Yes	./app/src/main/res, ./library/src/main/res, ./feature/src/main/res
dry_run	Run in dry-run mode (only report missing translations without translating). Set to "true" to enable dry-run mode.	"false"	Yes	"true" or "false"
log_trace	Enable detailed logging. Use "true" for verbose output.	"false"	Yes	"true"
llm_provider	LLM provider to use for translation. Options include "openai", "openrouter", "anthropic", "gemini", "azure", "ollama", etc. (via LiteLLM).	"openrouter"	Yes	"openai", "openrouter", "anthropic", "gemini", "ollama"
model	Model to use for translation. Supports all models from the chosen provider (e.g. gpt-4o-mini, google/gemini-2.5-flash, claude-3-5-sonnet-latest, ollama/llama3).	"google/gemini-2.5-flash"	Yes	"google/gemini-2.5-flash", "gpt-4o-mini", "claude-3-5-sonnet-latest"
openrouter_site_url	Your site URL for OpenRouter rankings. Used to identify your application in OpenRouter analytics.	"https://github.com/duartebarbosadev/AndroidResourceTranslator"	Yes	``
openrouter_site_name	Your site name for OpenRouter rankings. Used to identify your application in OpenRouter analytics.	"AndroidResourceTranslatorAction"	Yes	""
openrouter_send_site_info	Send site URL and name to OpenRouter for rankings. Set to "false" to disable.	"true"	Yes	"true" or "false"
project_context	Additional project context to include in translation prompts.	""	Yes	"Android launcher application"
ignore_folders	Comma-separated list of folder names to ignore during resource scanning. If empty, .gitignore file will be used instead.	""	Yes	"build,temp,cache"
include_reference_context	Include existing translations from the destination language as context when prompting the LLM. Set to "false" to disable the extra context entirely.	"true"	Yes	"false"
reference_context_limit	Maximum number of existing translations to send as context examples. Use "0" to skip sending any reference strings even if context is enabled.	"25"	Yes	"10"
batch_size	Maximum number of items to translate in a single batch API call. Decrease this if you are using a local model with reasoning that gets truncated by token limits.	"10"	Yes	"10", "5"

Environment Variables (API Keys)

Since the engine natively integrates LiteLLM, it automatically supports any LLM provider key by mapping them dynamically.

Set the appropriate key as a repository secret and pass it via env: in your workflow:

• Universal Variable: You can pass a generic API_KEY which works across all providers, or pass it directly on the command line via --api-key YOUR_KEY.
• Provider-Specific Variables: The script automatically detects and resolves {PROVIDER}_API_KEY depending on what you supply in llm_provider. For example:
  • OPENAI_API_KEY when using llm_provider: openai
  • OPENROUTER_API_KEY when using llm_provider: openrouter
  • ANTHROPIC_API_KEY when using llm_provider: anthropic
  • GEMINI_API_KEY when using llm_provider: gemini
  • GROQ_API_KEY when using llm_provider: groq
  • MISTRAL_API_KEY when using llm_provider: mistral
  • ... and any other LiteLLM-supported provider key!

Translation Report Output

After the translation process is executed, the action produces an output called translation_report. This report is generated in Markdown format and includes a detailed summary of all translations performed. The report contains:

• Module Information:
  Each module found in your Android project is listed along with its language-specific resources.
• Strings Translations:
  For each module and language, a table displays every key that was translated, including the original text and the resulting translation.
• Plural Resources Translations:
  If plural resources were translated, the report shows each plural resource name along with a table listing each plural quantity (e.g., one, few, many) and their corresponding translations.

This output is particularly useful for manual review and validation. In the provided advanced workflow, the report is automatically inserted into the body of a pull request, allowing maintainers to inspect the changes before merging.

Projects Using Android Resource Translator

We love to see our tool in action! Here are some projects that are using Android Resource Translator:

• Scrolless

Have a project using Android Resource Translator? Let us know by submitting a pull request to add your project to this list!

Contributing

Contributions are very welcome! If you have ideas for improvements or spot any issues, please open an issue or submit a pull request.

For detailed guidelines on how to contribute, please see our Contributing Guide.

License

This project is licensed under the MIT License.

If you have any questions or need assistance, feel free to open an issue or reach out.