translate-gpt-release-notes plugin

This project is a fastlane plugin. To get started with fastlane-plugin-translate_gpt_release_notes, add it to your project by running:

fastlane add_plugin translate_gpt_release_notes

• Ruby >= 3.1
• API key for at least one supported translation provider

Note: This plugin requires Ruby 3.1 or higher to ensure compatibility with the latest security patches in nokogiri.

translate-gpt-release-notes is a fastlane plugin that allows you to translate release notes or changelogs for iOS and Android apps using multiple AI translation providers. Based on translate-gpt by ftp27.

The plugin now supports 4 translation providers, giving you flexibility to choose based on cost, quality, and availability:

translate-gpt-release-notes takes the changelog file for the master locale (default: en-US), detects other locales based on the fastlane metadata folder structure, translates the changelog to all other languages using your chosen AI provider, and creates localized .txt changelog files in their respective folders.

Choose your preferred provider and set the corresponding environment variable:

# Option 1: OpenAI (default)
export OPENAI_API_KEY='your-openai-api-key'
# Or use the legacy variable (still supported)
export GPT_API_KEY='your-openai-api-key'

# Option 2: Anthropic Claude
export ANTHROPIC_API_KEY='your-anthropic-api-key'

# Option 3: Google Gemini
export GEMINI_API_KEY='your-gemini-api-key'

# Option 4: DeepL
export DEEPL_API_KEY='your-deepl-api-key'

lane :translate_release_notes do
  translate_gpt_release_notes(
    master_locale: 'en-US',
    platform: 'ios',
    context: 'This is an app about cute kittens'
  )
end

By default, the plugin uses OpenAI as the translation provider. This ensures backward compatibility with existing setups.

You can explicitly select a provider using the provider parameter:

# Use Anthropic Claude
translate_gpt_release_notes(
  provider: 'anthropic',
  master_locale: 'en-US',
  platform: 'ios'
)

# Use Google Gemini
translate_gpt_release_notes(
  provider: 'gemini',
  master_locale: 'en-US',
  platform: 'ios'
)

# Use DeepL
translate_gpt_release_notes(
  provider: 'deepl',
  master_locale: 'en-US',
  platform: 'ios'
)

Or set the default provider via environment variable:

export TRANSLATION_PROVIDER='anthropic'

translate_gpt_release_notes(
  provider: 'openai',              # Optional, this is the default
  openai_api_key: 'sk-...',        # Or use OPENAI_API_KEY env var
  model_name: 'gpt-5.2',           # Default model
  service_tier: 'flex',            # Options: auto, default, flex, priority
  temperature: 0.5,                # 0-2, lower = more deterministic
  master_locale: 'en-US',
  platform: 'ios',
  context: 'Fitness tracking app'
)

translate_gpt_release_notes(
  provider: 'anthropic',
  anthropic_api_key: 'sk-ant-...', # Or use ANTHROPIC_API_KEY env var
  model_name: 'claude-sonnet-4.5', # Default model
  temperature: 0.5,                # 0-1 for Anthropic
  master_locale: 'en-US',
  platform: 'ios',
  context: 'Finance management app'
)

translate_gpt_release_notes(
  provider: 'gemini',
  gemini_api_key: '...',           # Or use GEMINI_API_KEY env var
  model_name: 'gemini-2.5-flash',  # Default model
  temperature: 0.5,                # 0-1 for Gemini
  master_locale: 'en-US',
  platform: 'android',
  context: 'Social media app'
)

translate_gpt_release_notes(
  provider: 'deepl',
  deepl_api_key: '...',            # Or use DEEPL_API_KEY env var
  formality: 'less',               # Options: default, more, less
  master_locale: 'en-US',
  platform: 'ios',
  context: 'Casual gaming app'
)

Note: DeepL automatically detects free vs paid API keys (free keys end with :fx) and uses the appropriate endpoint.

The recommended approach is to set API keys via environment variables:

export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'
export GEMINI_API_KEY='...'
export DEEPL_API_KEY='...'

Alternatively, pass API keys directly (useful for CI/CD with secrets):

translate_gpt_release_notes(
  provider: 'anthropic',
  anthropic_api_key: ENV['ANTHROPIC_API_KEY'],
  master_locale: 'en-US',
  platform: 'ios'
)

You can configure multiple providers simultaneously and switch between them:

# Set up all providers
export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'
export GEMINI_API_KEY='...'

# Default to Gemini for cost savings
export TRANSLATION_PROVIDER='gemini'

If you're upgrading from a previous version that only supported OpenAI:

1. No breaking changes - Your existing setup will continue to work
2. Existing GPT_API_KEY still works - No need to rename your environment variable
3. Default provider is OpenAI - All existing configurations work unchanged

Optional improvements you can make:

• Rename GPT_API_KEY to OPENAI_API_KEY for clarity (both work)
• Set TRANSLATION_PROVIDER if you want to experiment with other providers
• Try different providers for different lanes (e.g., Gemini for development, Claude for production)

Before:

translate_gpt_release_notes(
  api_token: ENV['GPT_API_KEY'],
  model_name: 'gpt-5.2',
  master_locale: 'en-US'
)

After (still works, but cleaner):

translate_gpt_release_notes(
  provider: 'openai',
  master_locale: 'en-US'
)

Android has a limit of 500 characters for changelogs. The plugin handles this in two ways:

1. AI Providers (OpenAI, Anthropic, Gemini): The character limit is included in the translation prompt, asking the AI to stay within the limit
2. DeepL: Translations are truncated to 500 characters with a warning if they exceed the limit

If you frequently hit the limit, consider shortening your master locale changelog.

iOS has a limit of 4000 characters, which is rarely an issue for release notes.

All AI translation APIs cost money. Consider these tips:

• Use service_tier: 'flex' with OpenAI for lower prices (trades latency for cost)
• Google Gemini is generally the most cost-effective option
• DeepL offers competitive pricing for European languages
• The plugin skips translation if the source file hasn't changed (tracked via last_successful_run.txt)

Note: When using flex, the plugin automatically increases request_timeout to 900 seconds if set lower.

Cause: No API keys are set for any provider.

Solution: Set at least one provider's API key:

export OPENAI_API_KEY='your-key-here'

Cause: You specified a provider but haven't configured its API key.

Solution: Either configure the provider's API key or switch to a provider with configured credentials.

Cause: The provider name is not recognized.

Solution: Use one of the valid provider names: openai, anthropic, gemini, deepl.

Cause: The translated text is longer than 500 characters.

Solutions:

1. Shorten your source changelog
2. For DeepL, translations are automatically truncated
3. For AI providers, the prompt includes the limit but compliance isn't guaranteed

Cause: The translation request is taking too long.

Solutions:

1. Increase request_timeout parameter
2. For OpenAI flex tier, timeout is automatically increased to 900s
3. Consider using a faster provider (Gemini or DeepL)

Cause: Flex tier trades latency for lower cost.

Solution: This is expected behavior. If speed is critical, use service_tier: 'default' or service_tier: 'priority'.

OpenAI GPT

• ✅ Best for general-purpose translations
• ✅ Flexible and customizable
• ✅ Supports service tiers for cost control
• ❌ Can be expensive for high volume

Anthropic Claude

• ✅ Highest quality nuanced translations
• ✅ Excellent for complex or technical content
• ✅ Strong reasoning capabilities
• ❌ Slower than other options
• ❌ Higher cost

Google Gemini

• ✅ Most cost-effective
• ✅ Fast response times
• ✅ Good quality for standard content
• ❌ May struggle with very nuanced content

DeepL

• ✅ Best for European languages
• ✅ Purpose-built for translation
• ✅ Formality control
• ❌ Limited language support compared to AI providers
• ❌ May not handle app-specific context as well

If you have trouble using plugins, check out the Plugins Troubleshooting guide. For any other issues and feedback about this plugin, please submit it to this repository.

For more information about how the fastlane plugin system works, check out the Plugins documentation.

fastlane is the easiest way to automate beta deployments and releases for your iOS and Android apps. To learn more, check out fastlane.tools.

If you'd like to contribute to this plugin, please fork the repository and make your changes. When you're ready, submit a pull request explaining your changes.

This action is released under the MIT License.