btcpayserver/btcpayserver-translator
btcpayserver/btcpayserver-translator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3fb8b20bb2
btcpayserver-translator/README.md
Timothé 3fb8b20bb2 Update Readme.md
2026-06-12 10:57:16 +02:00

8.6 KiB
Raw Blame History

BTCPay Server Translator

A command-line tool to translate BTCPay Server's UI text to multiple languages using OpenRouter AI service. Now enjoy BTCPay Server in your local languages.

Features

  • Translates BTCPay Server's default English strings to any supported language
  • Uses OpenRouter API with various AI models
  • URL Support: Download translations directly from GitHub URLs
  • Batch processing with configurable concurrency and rate limiting
  • Secure configuration using environment variables
  • Resume capability for interrupted translations
  • Detailed logging and progress tracking

Setup

1. Get an OpenRouter API Key

  1. Go to OpenRouter.ai
  2. Sign up for an account
  3. Get your API key from the dashboard

2. Configure Environment Variables

Copy the example environment file:

cp env.example .env

Edit .env and set your API key:

# Required: Your OpenRouter API key
OPENROUTER_API_KEY=sk-or-v1-your-actual-api-key-here
# Optional: Override default settings
OPENROUTER_MODEL=add_your_model
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_SITE_NAME=BTCPayTranslator
OPENROUTER_APP_NAME=https://github.com/btcpayserver/btcpayserver

Usage

Run from the Translator/ directory. All commands below assume your shell's working directory is Translator/:

cd Translator && dotnet run -- <command>

List Available Languages

dotnet run -- list-languages

Translate to a Single Language

# Translate to Hindi
dotnet run -- translate --language hi

# Force retranslation of all strings
dotnet run -- translate --language hi --force

Batch Translation to Multiple Languages

# Translate to multiple languages
dotnet run -- batch --languages hi es fr de

# Continue on error (don't stop if one language fails)
dotnet run -- batch --languages hi es fr de --continue-on-error

# Force retranslation
dotnet run -- batch --languages hi es fr de --force

Check Translation Status

dotnet run -- status

Update Existing Translation with New Strings

Update Single Language

# Update Hindi translation with latest strings from GitHub
dotnet run -- update --language hi

Update Multiple Languages

# Update multiple specific languages
dotnet run -- batch-update --languages hi es fr de

# Continue on error (don't stop if one language fails)
dotnet run -- batch-update --languages hi es fr de --continue-on-error

Update All Existing Languages Automatically

# Automatically detect and update all translation files
dotnet run -- update-all

# Continue on error
dotnet run -- update-all --continue-on-error

How Update Commands Work:

  • Fetches the latest strings from BTCPayServer's GitHub repository (once for all languages in update-all)
  • Compares with your local translation file(s)
  • Only translates new strings that were added (e.g., if you have 2000 strings and GitHub has 2015, only 15 new strings are translated)
  • Removes strings that were deleted from the source
  • Preserves all existing translations
  • Maintains the same order as the source file

When to Use:

  • update - Update a single language
  • batch-update - Update specific languages you choose
  • update-all - Update all translation files in your translations directory automatically (most convenient!)

This is useful when BTCPayServer adds new features and strings. Instead of retranslating everything, you can just update with the new additions.

Refresh Keys Without Translating (placeholders)

If you just want to add the newly-added English keys to your translation files as placeholders (to translate later, by hand or with update), use refresh-keys. Unlike update, it does not call the AI service and does not require an OpenRouter API key.

# Refresh all translation files from a LOCAL source file (no download)
dotnet run -- refresh-keys --source-file ../btcpayserver/BTCPayServer/Services/Translations.Default.cs

# Refresh only specific languages
dotnet run -- refresh-keys --source-file ./Translations.Default.cs --languages fr es de

# Refresh from a running BTCPay Server (includes the DI-registered strings)
dotnet run -- refresh-keys --btcpay-url http://localhost:14142

# Without --source-file / --btcpay-url it falls back to the configured InputFile (GitHub)
dotnet run -- refresh-keys

How refresh-keys differs from update:

  • No AI / no API key - new keys are inserted with the English text as a placeholder value.
  • Insert-only - it never removes keys (so DI-registered strings not present in the static source are kept). It only adds keys that are missing.
  • Byte-preserving - existing entries (including _maintainer/_source metadata, ordering, and formatting) are left untouched; only new lines are added. Re-running it is a no-op once everything is present.

Options: --source-file <path> (local file, overrides the configured InputFile), --btcpay-url <url> (takes precedence over --source-file), --languages <codes> (optional filter; omit to refresh all files).

Fetching Translations from a Running BTCPay Server

By default the tool fetches strings by parsing Translations.Default.cs from GitHub. However, some strings are registered via Dependency Injection (by plugins, payment methods, etc.) and do not appear in that file.

When BTCPay Server is running in debug/cheat mode, it exposes a GET /cheat/translations/default-en endpoint that returns the complete set of all registered English strings. Pass --btcpay-url to any command to use it instead:

# 1. Start BTCPay Server in debug mode (cheatmode is enabled automatically)
cd path/to/btcpayserver/BTCPayServer
dotnet run --launch-profile Bitcoin

# 2. Run any translation command against the live instance
dotnet run -- update-all --btcpay-url http://localhost:14142
dotnet run -- translate --language ja --btcpay-url http://localhost:14142

You can also set it permanently in .env so you don't have to pass it every time:

TRANSLATION_BTCPAY_URL=http://localhost:14142

All commands work without --btcpay-url — it is purely optional. The only difference is that without it, the ~100 DI-registered strings are not included.

Supported Languages

The tool supports 100+ languages including:

  • Major Languages: Spanish (es), French (fr), German (de), Italian (it), Portuguese (pt), Russian (ru), Japanese (ja), Korean (ko), Chinese (zh-cn, zh-tw), Arabic (ar), Hindi (hi)
  • European Languages: Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Hungarian, etc.
  • Asian Languages: Bengali, Tamil, Telugu, Malayalam, Thai, Vietnamese, Indonesian, etc.
  • Regional Languages: Catalan, Basque, Welsh, Irish, Scottish Gaelic, etc.

Configuration

Environment Variables

Variable Default Description
OPENROUTER_API_KEY (required) Your OpenRouter API key
OPENROUTER_MODEL anthropic/claude-3.5-sonnet AI model to use
OPENROUTER_BASE_URL https://openrouter.ai/api/v1 OpenRouter API base URL
OPENROUTER_SITE_NAME BTCPayTranslator Site name for analytics
OPENROUTER_APP_NAME https://github.com/btcpayserver/btcpayserver App name for analytics
TRANSLATION_BTCPAY_URL (empty) BTCPay Server base URL for fetching all strings in debug mode

Application Settings (appsettings.json)

{
  "Translation": {
    "BatchSize": 50,
    "MaxRetries": 3,
    "DelayBetweenRequests": 1000,
    "InputFile": "https://raw.githubusercontent.com/btcpayserver/btcpayserver/master/BTCPayServer/Services/Translations.Default.cs",
    "OutputDirectory": "../translations",
    "BTCPayUrl": ""
  }
}

Input File Configuration:

  • URL Support: You can use either a local file path or a URL to the BTCPayServer translations file
  • GitHub URLs: The tool automatically converts GitHub blob URLs to raw URLs for direct content access
  • Examples:
    • URL: https://raw.githubusercontent.com/btcpayserver/btcpayserver/master/BTCPayServer/Services/Translations.Default.cs
    • Local: ../BTCPayServer/Services/Translations.Default.cs

Output

Translated files are saved to the configured output directory with the following structure:

translations/
├── hindi.json
├── spanish.json
├── french.json
└── ...

Each translation file includes:

  • All translated strings
  • Metadata about the language
  • Progress reports and error logs

Help us make it better

All the translations are AI generated and AI can make mistakes sometimes, so if you recognize a string that might need to be edited, share a pull request.