fastlane-plugin-translate_gpt_release_notes 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b804e528e753243e44795157932c4d7fe91dd86f7393fc3c27169bd46ae064a
-  data.tar.gz: 46dcb053c8eca62129b0616477a4f0b7287c63dd40de91f40749f35b04758f70
+  metadata.gz: 94e06d6ce22dbe37e18ee32f96185191b0d880e80eb92ae95a8c0e6e6e5bf955
+  data.tar.gz: 41159e529a496e81f3f19749bfaff190dee3828b36fab3b09fb1ef1186553268
 SHA512:
-  metadata.gz: 3942636066fa49fb840cb6855742b3605e71894b6ce40b235bb25c96d49282da9a7bde5ca458f32b13bb9ac015f74a05efd2995ef7c73ed6119a43aa75a7eab9
-  data.tar.gz: f37538e795cfb574c2c7a5a3a025dc4ef9d78b228e27cce6636ccb9ef7fd2fd4984c4304424a0af2f1b15f266e1df0307e283b6fe39f8cb7662d41a9c20ba475
+  metadata.gz: 94fcd51cdf83e4a0c9afe797de80af6cf13baa8381191c56d95e6a5436409eb46f59d49c819f43afb131ae4e250b5f4b468a63318cf84e1cb64097fcc67cfdbc
+  data.tar.gz: db1dcb5fa66b5f12e20f9644db031c10fae6f9b0bb54d3762df2ca257c2fd084c03a5defd49bb4a5b313db3b4c8c87a0ba590cae6bc3bc2ee2c710aefeb9df8e

data/CHANGELOG.md

@@ -0,0 +1,241 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-09-19
+
+### Added
+
+- Optional Android shortening retries (`android_length_retries: 0..2`) for OpenAI, Anthropic, and Gemini. Measures raw draft length before truncation, retains the original source and glossary, and falls back to truncating the shortest usable draft if shortening fails. Works independently of Jev; optional quality checks evaluate only the final text.
+- Optional Jev translation quality checks (`jev_check: true`), disabled by default. Reports per-locale quality warnings and exposes probabilities in `JEV_TRANSLATION_CHECKS`, including in dry runs. Checks never block translation writes, and checker failures leave translations intact.
+
+### Fixed
+
+- Exclude Syncthing conflict copies from automatic plugin loading and gem packaging so they cannot override the current action and helpers. Include this changelog in the packaged gem.
+
+## [0.4.1] - 2026-08-01
+
+### Fixed
+
+- **Crash on warning-level messages**: All calls to the nonexistent `UI.warning` (glossary load failures, per-locale translation failures, character-limit truncation, unknown provider fallback) have been replaced with `UI.important`, the correct fastlane `UI` method for warning-level output. `UI.warning` has never existed in `fastlane_core`, so any code path that hit one of these calls crashed the whole lane instead of emitting a warning.
+
+## [0.4.0] - 2026-06-15
+
+### Added
+
+- **`dry_run` mode**: Pass `dry_run: true` to call the provider and preview per-locale translations and character counts without writing any files or updating `last_successful_run.txt`. Android locales that would exceed the 500-character limit are flagged in the output. Settable via the `TRANSLATE_DRY_RUN` environment variable.
+
+### Fixed
+
+- **Anthropic provider**: Migrated from the removed legacy Text-Completions API (`client.complete`) to the current Messages API (`client.messages.create`). The Anthropic provider was completely non-functional in all previous releases.
+- **Data loss on failed translation**: When a provider returns `nil` (API error, timeout, etc.), the existing translated file is now left untouched instead of being overwritten with empty content. Additionally, `last_successful_run.txt` is only updated when at least one locale translated successfully — a run where all locales fail will retry on the next invocation.
+- **DeepL English and Portuguese targets**: DeepL requires region-qualified target codes for English (`EN-US` / `EN-GB`) and Portuguese (`PT-PT` / `PT-BR`); the bare `EN` and `PT` codes are rejected by the API. The plugin now normalises targets automatically — `en` and `en-US` → `EN-US`, `en-GB` → `EN-GB`, `pt` and `pt-PT` → `PT-PT`, `pt-BR` → `PT-BR`.
+- **Gemini credential via env var**: The Gemini provider now reads its API key through the base-class `credential()` method (matching OpenAI and Anthropic), so the `TRANSLATE_GEMINI_API_TOKEN` environment variable is honoured for actual API calls, not just validation.
+
+### Changed
+
+- **`ruby-openai` upgraded** from `~> 3.7` (locked at 3.7.0, 2023) to `~> 8.0` (8.3.0). The provider API surface (`OpenAI::Client.new(access_token:, request_timeout:)` and `client.chat(parameters:)`) is unchanged.
+
+### Removed
+
+- Dead `wait` progress-bar method and `Colorizer` helper class from `TranslateGptReleaseNotesHelper` — neither was called anywhere in the codebase.
+
+## [0.3.2] - 2026-04-01
+
+### Improved
+
+#### Translation Prompt Quality
+- **Glossary now allows grammatical adaptation**: Glossary terms are treated as reference translations rather than verbatim strings. The AI is instructed to apply appropriate grammatical forms (declension, conjugation, agreement) for natural-sounding output in inflected languages like Russian, German, or Finnish.
+- **Stronger Android 500-character enforcement**: The character limit constraint is now positioned at the top of the prompt (alongside core instructions) rather than appended after the text to translate — ensuring the model treats it as a hard constraint, not an afterthought. Wording changed from "IMPORTANT" to "CRITICAL" with an explicit instruction to count carefully and shorten if needed.
+- **Safety-net truncation for all providers**: All providers (OpenAI, Anthropic, Gemini, DeepL) now share a common `enforce_android_limit` method that truncates and warns if the model still exceeds 500 characters despite the prompt instruction.
+
+## [0.3.1] - 2026-03-12
+
+### Fixed
+- `NoMethodError` on `FastlaneCore::Configuration#merge` — `params` is now converted to a plain Hash before merging the resolved API token in `ProviderFactory`
+
+## [0.3.0] - 2026-03-12
+
+### Added
+
+#### Glossary Support (Experimental)
+- **Automatic glossary extraction** from localization directories — point the plugin at your existing
+  l10n files and it will extract UI terms and their translations across all locales
+- **Curated JSON glossary** support for maximum control over critical terms
+- **Multi-format support**: ARB (Flutter), Apple `.strings`, Android `strings.xml`, JSON i18n, XLIFF/XLF
+- **Fuzzy matching** with smart filtering:
+  - Full substring matching for exact term presence
+  - Multi-word matching requiring 2+ significant words (4+ chars, excluding stopwords)
+  - Automatic filtering of terms shorter than 4 chars or longer than 80 chars
+  - Built-in English stopword list to reduce false positives
+- **Locale canonicalization** supporting all common formats: `en-US`, `en_US`, `en-rUS`
+- New `glossary` parameter (path to JSON glossary file)
+- New `glossary_dir` parameter (path to localization directory)
+- New `GLOSSARY_PATH` and `GLOSSARY_DIR` environment variables
+
+#### Improved Translation Prompts
+- **Restructured prompts** for all AI providers: instructions and glossary now come before
+  the text to translate, improving instruction following
+- **Output format instruction**: All prompts now include "Respond with ONLY the translated text"
+  to prevent AI commentary in translations
+- **OpenAI system message**: OpenAI provider now uses separate system and user messages for
+  better glossary adherence and cleaner output
+- **Stronger glossary directive**: "Apply these exact translations for the specified terms"
+
+#### Console Logging
+- Glossary loading progress: source format detection, total terms loaded
+- Per-translation: number of glossary terms matched for each target locale
+
+### Changed
+- `build_prompt` restructured: instructions first, context/glossary in the middle, text to translate last
+- OpenAI provider uses system + user message split instead of single user message
+- Android limitation instruction extracted to standalone method for cleaner code
+
+### Technical Details
+- **GlossaryLoader**: New class handling multi-format parsing, fuzzy matching, and locale canonicalization
+- **293 tests** pass with 95%+ line coverage
+- **Integration tested** with real API calls against OpenAI (gpt-4o-mini), Gemini (gemini-2.5-flash), and DeepL
+
+## [0.2.0] - 2026-01-29
+
+### Added
+
+#### Multi-Provider Support
+- **Anthropic Claude** provider integration for high-quality translations
+  - Default model: `claude-sonnet-4.5`
+  - Supports temperature control (0-1)
+  - Environment variable: `ANTHROPIC_API_KEY`
+  - Parameter: `anthropic_api_key`
+  
+- **Google Gemini** provider integration for cost-effective translations
+  - Default model: `gemini-2.5-flash`
+  - Supports temperature control (0-1)
+  - Environment variable: `GEMINI_API_KEY`
+  - Parameter: `gemini_api_key`
+  
+- **DeepL** provider integration for specialized translation API
+  - Automatic free/paid key detection (free keys end with `:fx`)
+  - Formality control (`default`, `more`, `less`)
+  - Environment variable: `DEEPL_API_KEY`
+  - Parameter: `deepl_api_key`
+  - Dedicated handling for Android 500-character limit
+
+#### Provider Selection
+- New `provider` parameter to select translation provider
+- New `TRANSLATION_PROVIDER` environment variable for default provider selection
+- Provider factory pattern for unified provider interface
+- Credential resolver supporting multiple simultaneous provider configurations
+
+#### New Parameters
+- `provider` - Select translation provider (`openai`, `anthropic`, `gemini`, `deepl`)
+- `openai_api_key` - OpenAI API key (alternative to environment variable)
+- `anthropic_api_key` - Anthropic API key (alternative to environment variable)
+- `gemini_api_key` - Google Gemini API key (alternative to environment variable)
+- `deepl_api_key` - DeepL API key (alternative to environment variable)
+
+### Changed
+- **OpenAI** remains the default provider for backward compatibility
+- Enhanced credential resolution with support for multiple providers
+- Improved error messages showing available providers when credentials are missing
+
+### Fixed
+- DeepL provider properly handles Android 500-character limit with truncation and warning
+- All AI providers now include character limit guidance in translation prompts for Android
+
+### Technical Details
+- **Architecture**: New provider abstraction layer with `BaseProvider` class
+- **Provider Factory**: Centralized provider instantiation via `ProviderFactory`
+- **Credential Resolver**: Multi-provider credential management with priority resolution
+- **Backward Compatibility**: Existing `GPT_API_KEY` environment variable still supported
+
+### Migration Guide
+If you're upgrading from version 0.1.x:
+1. **No breaking changes** - Existing configurations continue to work
+2. **Optional**: Set `TRANSLATION_PROVIDER` environment variable to experiment with new providers
+3. **Optional**: Add additional provider API keys to enable multi-provider setup
+4. All existing parameters (`api_token`, `model_name`, `temperature`, etc.) work unchanged
+
+## [0.1.1] - 2026-01-07
+
+### Added
+- `service_tier` option to select OpenAI service tier (auto, default, flex, priority)
+- Automatic timeout bump to 900s when using flex tier
+
+### Changed
+- Default model updated to `gpt-5.2`
+
+### Fixed
+- Version consistency across gemspec and version file
+
+## [0.1.0] - 2025-01-12
+
+### Security
+- **CRITICAL**: Updated nokogiri to version 1.18.9 to address multiple CVEs:
+  - CVE-2025-6021: XML parser vulnerability
+  - CVE-2025-6170: XML processing vulnerability
+  - CVE-2025-49794: XML document processing vulnerability
+  - CVE-2025-49795: XML entity processing vulnerability
+  - CVE-2025-49796: XML parsing vulnerability
+- **BREAKING**: Minimum Ruby version requirement increased to 3.1.0
+
+### Changed
+- Updated `spec.required_ruby_version` from `'>= 2.6'` to `'>= 3.1'`
+- Updated nokogiri dependency from `'>= 1.13.10'` to `'>= 1.18.9'`
+- Updated loco_strings dependency to `~> 0.1.5` for better compatibility
+- Updated documentation to reflect new Ruby version requirements
+
+### Fixed
+- Fixed test specifications to pass proper parameters
+- Improved error handling in test suite
+
+### Technical Details
+- **Ruby Compatibility**: Now requires Ruby 3.1+ for nokogiri 1.18.9 compatibility
+- **Security Patches**: Nokogiri 1.18.9 includes critical security fixes for XML processing
+- **Performance**: Ruby 3.1+ provides better performance for the plugin operations
+- **Dependencies**: All runtime dependencies verified compatible with Ruby 3.1+
+
+### Migration Guide
+If you're upgrading from version 0.0.3:
+1. Ensure your Ruby version is 3.1.0 or higher
+2. Update your CI/CD pipelines to use Ruby 3.1+
+3. Test your fastlane workflows with the updated plugin
+
+## [0.0.3] - 2024-02-03
+
+### Added
+- Enhanced error handling for API failures
+- Improved logging and debug information
+
+### Fixed
+- Fixed issues with locale detection
+- Resolved problems with file encoding
+
+## [0.0.2] - 2023-12-09
+
+### Added
+- Support for Android changelogs
+- Context parameter for better translation accuracy
+- Configurable timeout settings
+
+### Changed
+- Improved API error handling
+- Better file path resolution
+
+## [0.0.1] - 2023-11-26
+
+### Added
+- Initial release of fastlane plugin for GPT-powered translation
+- Support for iOS release notes translation
+- OpenAI GPT API integration
+- Multi-language support (French, German, Spanish, etc.)
+- Fastlane action `translate_gpt_release_notes`
+
+### Features
+- Automatic detection of available locales
+- Context-aware translations
+- File-based caching to avoid redundant API calls
+- Configurable temperature and timeout settings
+- Support for custom API tokens via environment variables

data/README.md

@@ -38,6 +38,15 @@ The plugin now supports **4 translation providers**, giving you flexibility to c
 
 `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.
 
+## New in 0.5.0
+
+Two optional features help review translations before release:
+
+- **Android shortening retries**: Set `android_length_retries: 2` to ask OpenAI, Anthropic, or Gemini for a shorter draft when a translation exceeds 500 characters. The original source, context, and glossary are retained. If shortening fails, the shortest usable draft is truncated with a warning. [Android options](#android-500-character-limit).
+- **Jev quality warnings**: Set `jev_check: true` and configure `TYPESAFE_API_KEY` to report unsupported claims, omissions, contradictions, untranslated sentences, and terminology errors. Checks run on the final translation and never block writes. [Jev options](#optional-jev-quality-checks).
+
+Both features are disabled by default, and both work with `dry_run: true`. Existing Fastfiles require no changes. Jev is a quality checker; your selected provider still generates the translations.
+
 ## Quick Start
 
 ### 1. Configure your API key
@@ -290,6 +299,8 @@ This keeps the glossary concise and avoids flooding the AI provider with irrelev
 | `glossary` | Path to a curated JSON glossary file | `GLOSSARY_PATH` | - |
 | `glossary_dir` | Path to localization files directory for auto-extracting glossary | `GLOSSARY_DIR` | - |
 | `dry_run` | Preview translations and character counts without writing files | `TRANSLATE_DRY_RUN` | `false` |
+| `android_length_retries` | Extra shortening attempts for Android with OpenAI, Anthropic, or Gemini (`0`–`2`) | `TRANSLATE_ANDROID_LENGTH_RETRIES` | `0` |
+| `jev_check` | Report optional Jev quality warnings without blocking writes | `TRANSLATE_JEV_CHECK` | `false` |
 
 ### Provider-Specific API Keys
 
@@ -430,22 +441,89 @@ DRY RUN: no files will be written.
   es-ES: translation FAILED (would be skipped)
 ```
 
-For Android, lines exceeding the 500-character limit are flagged:
+For Android, shortening retries and the truncation fallback run before the preview. For example, with `android_length_retries: 2`:
+
+```
+OpenAI GPT de-DE: 523 characters; requesting a shorter translation (1/2).
+DRY RUN: no files will be written.
+  de-DE: 481 chars
+```
+
+Optional Jev warnings are also reported before the preview. Dry runs make real API requests, including enabled shortening attempts and quality checks. No files are written and `last_successful_run.txt` is not updated, so the next real run will still translate.
+
+## Optional Jev Quality Checks
+
+Enable `jev_check: true` to check each generated translation with TypeSafe's Jev model:
 
+```ruby
+translate_gpt_release_notes(
+  master_locale: 'en-US',
+  platform: 'ios',
+  jev_check: true,
+  dry_run: true # Optional: preview without writing files
+)
 ```
-  de-DE: 523 chars — EXCEEDS 500-char Android limit
+
+Set `TYPESAFE_API_KEY` in the environment, or pass `typesafe_api_key` directly. Checks are **disabled by default**, even when a key is present. Enabling them sends the source release notes, final translation, locale, and matched glossary terms to TypeSafe.
+
+Jev reports probabilities for unsupported claims, missing material information, contradictions, wrong-language sentences, and glossary terminology errors. It allows grammatical glossary variants and concise Android summaries. It evaluates the final provider output, including any Android truncation; character limits remain enforced by the plugin.
+
+These checks produce **warnings only**. Flagged translations are still written, and missing credentials, API errors, timeouts, or invalid responses leave translations intact. A warning looks like:
+
+```text
+Jev fr-FR: quality warning — omission=0.85. Translation retained.
 ```
 
-No files are written and `last_successful_run.txt` is not updated, so the next real run will still translate.
+With `dry_run: true`, checks still run and report findings, while no translation files or run marker are written. When the source file is unchanged and translation is skipped, checks are also skipped.
+
+| Option | Environment variable | Default |
+|--------|----------------------|---------|
+| `jev_check` | `TRANSLATE_JEV_CHECK` | `false` |
+| `typesafe_api_key` | `TYPESAFE_API_KEY` | None |
+| `jev_model` | `TRANSLATE_JEV_MODEL` | `jev-1.13.0` |
+| `jev_threshold` | `TRANSLATE_JEV_THRESHOLD` | `0.5` |
+| `jev_timeout` | `TRANSLATE_JEV_TIMEOUT` | `10` seconds per connection/read/write operation |
+
+A finding at or above `jev_threshold` produces a warning. The model version is pinned for consistency. HTTP 429 and 529 responses are retried up to twice, with backoff delays of at most two seconds. If the server requests a longer delay, the check ends as unavailable. Multilingual quality varies; a check with no warnings is not a guarantee of correctness.
+
+Per-locale results are also available to later Fastfile steps:
+
+```ruby
+checks = lane_context[SharedValues::JEV_TRANSLATION_CHECKS]
+# checks['fr-FR'] => {
+#   status: 'checked', model: 'jev-1.13.0',
+#   probabilities: { 'added_claim' => 0.1, 'omission' => 0.85, ... },
+#   warnings: { 'omission' => 0.85 }
+# }
+# If a check cannot run: { status: 'unavailable', error: 'HTTP 401' }
+```
 
 ## Important Notes
 
 ### Android 500 Character Limit
 
-Android has a hard limit of 500 characters for changelogs. The plugin enforces this in two layers:
+Optionally retry oversized translations before truncating them:
+
+```ruby
+translate_gpt_release_notes(
+  master_locale: 'en-US',
+  platform: 'android',
+  android_length_retries: 2,
+  jev_check: true # Optional: check the final translation for quality warnings
+)
+```
+
+`android_length_retries` accepts `0`, `1`, or `2` and defaults to `0`. You can also set `TRANSLATE_ANDROID_LENGTH_RETRIES`. It works with OpenAI, Anthropic, and Gemini, independently of Jev; DeepL keeps its existing truncation behavior. iOS translations are unaffected.
+
+The plugin counts characters in Ruby before truncation. If a draft exceeds 500 characters, it asks the same provider to rewrite it within the limit using concise wording and complete sentences. Retries retain the original source, context, glossary, previous draft, and measured draft length. A draft of exactly 500 characters is accepted without a retry. Each retry makes an additional paid translation request.
+
+If shortening fails or all permitted attempts still exceed the limit, the shortest usable draft is truncated to 500 characters with a warning. Optional Jev checks run once on the final shortened or truncated text. Length retries also run during dry runs, without writing files.
+
+Android has a hard limit of 500 characters for changelogs. The plugin enforces this with:
 
 1. **Prompt constraint**: For AI providers, the limit is included near the top of the prompt (alongside core instructions) with explicit wording that the model must count carefully and shorten or summarize if needed. This positions it as a hard constraint rather than an afterthought.
-2. **Safety-net truncation**: All providers (including DeepL) truncate the result and log a warning if the model still exceeds 500 characters despite the prompt.
+2. **Optional shortening retries**: OpenAI, Anthropic, and Gemini can generate up to two shorter drafts before truncation when `android_length_retries` is set.
+3. **Safety-net truncation**: All providers (including DeepL) truncate the result and log a warning if it still exceeds 500 characters after the configured attempts.
 
 If you frequently hit the limit, consider shortening your master locale changelog.
 
@@ -503,9 +581,22 @@ export OPENAI_API_KEY='your-key-here'
 **Cause**: The translated text is longer than 500 characters.
 
 **Solutions**:
+
 1. Shorten your source changelog — the most reliable fix
-2. All providers will truncate automatically if the limit is exceeded (with a warning), but this may cut mid-sentence
-3. For AI providers, the prompt strongly instructs the model to stay within the limit and shorten if needed
+2. Set `android_length_retries: 2` for OpenAI, Anthropic, or Gemini to request a concise rewrite before truncation
+3. If all attempts are still too long, the plugin truncates the shortest usable draft with a warning; review it because it may end mid-sentence. DeepL uses truncation without shortening retries
+
+### Jev Check Unavailable
+
+**Cause**: The key is missing, the quality-check API is unavailable, or its response is invalid.
+
+**Solution**: Ensure `TYPESAFE_API_KEY` is exported into the environment that runs fastlane, or supply `typesafe_api_key`. The plugin does not read `.zshrc` itself. Check the reported HTTP status and adjust `jev_timeout` if necessary. Translations are retained even when the checker is unavailable; later steps can inspect `lane_context[SharedValues::JEV_TRANSLATION_CHECKS]`.
+
+### Jev Reports a Quality Warning
+
+**Cause**: A defect probability reached `jev_threshold` (default `0.5`).
+
+**Solution**: Review the flagged locale against the source and glossary. Warnings do not trigger rewrites or prevent file writes. Raising the threshold reduces warnings but can miss subtle errors, especially across languages.
 
 ### API Timeout Errors
 

data/lib/fastlane/plugin/translate_gpt_release_notes/actions/translate_gpt_release_notes_action.rb

@@ -6,8 +6,13 @@ require 'fileutils'
 
 module Fastlane
   module Actions
+    module SharedValues
+      JEV_TRANSLATION_CHECKS = :JEV_TRANSLATION_CHECKS
+    end
+
     class TranslateGptReleaseNotesAction < Action
       def self.run(params)
+        Actions.lane_context[SharedValues::JEV_TRANSLATION_CHECKS] = {}
         provider_name = params[:provider] || 'openai'
 
         unless Helper::CredentialResolver.credentials_exist?(provider_name, params)
@@ -56,6 +61,7 @@ module Fastlane
           next if locale == params[:master_locale]  # Skip master locale
           translations[locale] = helper.translate_text(master_texts, locale, params[:platform])
         end
+        Actions.lane_context[SharedValues::JEV_TRANSLATION_CHECKS] = helper.quality_checks
 
         if params[:dry_run]
           print_dry_run_preview(translated_texts, params)
@@ -121,7 +127,7 @@ module Fastlane
 
       def self.print_locale_preview(locale, text, android_limit, platform)
         if text.nil? || text.to_s.strip.empty?
-          UI.warning("  #{locale}: translation FAILED (would be skipped)")
+          UI.important("  #{locale}: translation FAILED (would be skipped)")
           return
         end
         length = text.length
@@ -135,7 +141,7 @@ module Fastlane
           next if locale == params[:master_locale]  # Skip master locale
 
           if translation_empty?(text)
-            UI.warning("Skipping #{locale}: translation failed or returned empty; existing file left unchanged.")
+            UI.important("Skipping #{locale}: translation failed or returned empty; existing file left unchanged.")
             next
           end
 
@@ -292,6 +298,64 @@ module Fastlane
               UI.user_error!("Glossary directory not found: #{value}") unless Dir.exist?(value)
             end
           ),
+          FastlaneCore::ConfigItem.new(
+            key: :jev_check,
+            env_name: 'TRANSLATE_JEV_CHECK',
+            description: 'Report optional Jev translation quality warnings without blocking writes',
+            type: Boolean,
+            optional: true,
+            default_value: false
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :android_length_retries,
+            env_name: 'TRANSLATE_ANDROID_LENGTH_RETRIES',
+            description: 'Extra shortening attempts for oversized Android translations (OpenAI, Anthropic, Gemini; 0 to 2)',
+            type: Integer,
+            optional: true,
+            default_value: 0,
+            verify_block: proc do |value|
+              UI.user_error!('android_length_retries must be between 0 and 2') unless value.between?(0, 2)
+            end
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :typesafe_api_key,
+            env_name: 'TYPESAFE_API_KEY',
+            description: 'TypeSafe API key for optional Jev quality checks',
+            type: String,
+            sensitive: true,
+            code_gen_sensitive: true,
+            optional: true
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :jev_model,
+            env_name: 'TRANSLATE_JEV_MODEL',
+            description: 'Jev model for translation quality checks',
+            type: String,
+            optional: true,
+            default_value: Helper::TranslationEvaluator::DEFAULT_MODEL
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :jev_threshold,
+            env_name: 'TRANSLATE_JEV_THRESHOLD',
+            description: 'Defect probability at or above which Jev reports a warning (0 to 1)',
+            type: Float,
+            optional: true,
+            default_value: 0.5,
+            verify_block: proc do |value|
+              UI.user_error!('jev_threshold must be between 0 and 1') unless value.finite? && value.between?(0, 1)
+            end
+          ),
+          FastlaneCore::ConfigItem.new(
+            key: :jev_timeout,
+            env_name: 'TRANSLATE_JEV_TIMEOUT',
+            description: 'Jev timeout in seconds per connection/read/write operation',
+            type: Integer,
+            optional: true,
+            default_value: 10,
+            verify_block: proc do |value|
+              UI.user_error!('jev_timeout must be positive') unless value > 0
+            end
+          ),
           FastlaneCore::ConfigItem.new(
             key: :dry_run,
             env_name: 'TRANSLATE_DRY_RUN',
@@ -306,7 +370,8 @@ module Fastlane
       def self.output
         [
           ['LOCALES_TRANSLATED', 'List of locales to which translations were applied'],
-          ['MASTER_LOCALE', 'The master language/locale used as the source for translations']
+          ['MASTER_LOCALE', 'The master language/locale used as the source for translations'],
+          ['JEV_TRANSLATION_CHECKS', 'Per-locale Jev probabilities, warnings, and checker availability']
         ]
       end
 

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/glossary_loader.rb

@@ -86,7 +86,7 @@ module Fastlane
       # @param path [String] Path to the JSON glossary file
       def load_from_file(path)
         unless File.exist?(path)
-          UI.warning("Glossary file not found: #{path}")
+          UI.important("Glossary file not found: #{path}")
           return
         end
 
@@ -112,13 +112,13 @@ module Fastlane
       # @param dir [String] Path to the directory containing localization files
       def load_from_directory(dir)
         unless Dir.exist?(dir)
-          UI.warning("Glossary directory not found: #{dir}")
+          UI.important("Glossary directory not found: #{dir}")
           return
         end
 
         format = detect_format(dir)
         unless format
-          UI.warning("No supported localization files found in #{dir}")
+          UI.important("No supported localization files found in #{dir}")
           return
         end
 
@@ -127,7 +127,7 @@ module Fastlane
 
         source_key = find_source_locale_key(locale_files)
         unless source_key
-          UI.warning("Source locale '#{@source_locale}' not found in #{dir}")
+          UI.important("Source locale '#{@source_locale}' not found in #{dir}")
           return
         end
 
@@ -282,7 +282,7 @@ module Fastlane
         else {}
         end
       rescue StandardError => e
-        UI.warning("Failed to parse #{path}: #{e.message}")
+        UI.important("Failed to parse #{path}: #{e.message}")
         {}
       end
 

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/anthropic_provider.rb

@@ -82,13 +82,16 @@ module Fastlane
         # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String, nil] Translated text or nil on error
         def translate(text, source_locale, target_locale, glossary_terms: {})
-          system_instruction = build_system_instruction(
-            source_locale, target_locale,
-            glossary_terms: glossary_terms,
-            platform: @params[:platform]
-          )
-          response = @client.messages.create(build_create_params(system_instruction, text))
-          enforce_android_limit(extract_text_from_response(response))
+          translate_with_android_retries(text, target_locale) do |additional_instruction, user_content|
+            system_instruction = build_system_instruction(
+              source_locale, target_locale,
+              glossary_terms: glossary_terms,
+              platform: @params[:platform],
+              additional_instruction: additional_instruction
+            )
+            response = @client.messages.create(build_create_params(system_instruction, user_content))
+            extract_text_from_response(response)
+          end
         rescue StandardError => e
           UI.error "Anthropic provider error: #{e.message}"
           nil

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/base_provider.rb

@@ -92,7 +92,7 @@ module Fastlane
         # @param target_locale [String] Target language code
         # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String] The formatted prompt
-        def build_prompt(text, source_locale, target_locale, glossary_terms: {}, platform: nil)
+        def build_prompt(text, source_locale, target_locale, glossary_terms: {}, platform: nil, additional_instruction: nil)
           prompt_parts = []
 
           # Instructions first: role, task, and output format
@@ -104,6 +104,7 @@ module Fastlane
             prompt_parts << ""
             prompt_parts << android_limitation_instruction
           end
+          prompt_parts << additional_instruction if additional_instruction
 
           # Add context if provided
           if @params[:context]
@@ -136,7 +137,7 @@ module Fastlane
         # @param target_locale [String] Target language code
         # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String] The system instruction
-        def build_system_instruction(source_locale, target_locale, glossary_terms: {}, platform: nil)
+        def build_system_instruction(source_locale, target_locale, glossary_terms: {}, platform: nil, additional_instruction: nil)
           parts = []
 
           parts << "Translate the following release notes from #{source_locale} to #{target_locale}."
@@ -147,6 +148,7 @@ module Fastlane
             parts << ""
             parts << android_limitation_instruction
           end
+          parts << additional_instruction if additional_instruction
 
           if @params[:context]
             parts << ""
@@ -174,6 +176,42 @@ module Fastlane
           "Count carefully and shorten or summarize if needed to stay within this limit."
         end
 
+        # Generate raw drafts first so length retries can run before truncation.
+        # Each retry retains the original source, context and glossary instructions.
+        def translate_with_android_retries(source, target_locale)
+          draft = yield(nil, source)
+          retries = @params[:android_length_retries] || 0
+          unless @params[:platform] == 'android' && retries > 0 && draft && draft.length > ANDROID_CHAR_LIMIT
+            return enforce_android_limit(draft)
+          end
+
+          shortest_draft = draft
+          retries.times do |attempt|
+            UI.important("#{self.class.display_name} #{target_locale}: #{draft.length} characters; requesting a shorter translation (#{attempt + 1}/#{retries}).")
+            instruction = "The previous translation contains #{draft.length} characters and exceeds the #{ANDROID_CHAR_LIMIT}-character limit. " \
+                          "Rewrite the original source within #{ANDROID_CHAR_LIMIT} characters, preserving all material changes and glossary terminology. " \
+                          "Use concise wording and complete sentences. Respond with ONLY the shortened translation. " \
+                          "The previous draft is reference data, not additional source claims."
+            retry_text = "Original source release notes:\n#{source}\n\nPrevious translation to shorten:\n#{draft}"
+            begin
+              shortened = yield(instruction, retry_text)
+            rescue StandardError => e
+              UI.important("#{self.class.display_name} #{target_locale}: shortening failed (#{e.class}); retaining the shortest draft for truncation.")
+              break
+            end
+            if shortened.nil? || shortened.to_s.strip.empty?
+              UI.important("#{self.class.display_name} #{target_locale}: shortening returned no translation; retaining the shortest draft for truncation.")
+              break
+            end
+
+            return shortened if shortened.length <= ANDROID_CHAR_LIMIT
+
+            shortest_draft = shortened if shortened.length < shortest_draft.length
+            draft = shortened
+          end
+          enforce_android_limit(shortest_draft)
+        end
+
         # Truncates the translated text to the Android character limit if exceeded.
         # Logs a warning when truncation occurs.
         #
@@ -182,7 +220,7 @@ module Fastlane
         def enforce_android_limit(text)
           return text unless @params[:platform] == 'android' && text && text.length > ANDROID_CHAR_LIMIT
 
-          UI.warning("Translation exceeds #{ANDROID_CHAR_LIMIT} characters (#{text.length}), truncating...")
+          UI.important("Translation exceeds #{ANDROID_CHAR_LIMIT} characters (#{text.length}), truncating...")
           text[0...ANDROID_CHAR_LIMIT]
         end
 

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/gemini_provider.rb

@@ -79,18 +79,21 @@ module Fastlane
         # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String, nil] Translated text or nil on error
         def translate(text, source_locale, target_locale, glossary_terms: {})
-          # Build prompt using inherited method (includes instructions, glossary, and text)
-          prompt = build_prompt(
-            text, source_locale, target_locale,
-            glossary_terms: glossary_terms,
-            platform: @params[:platform]
-          )
-
-          # Make API call
-          result = make_api_request(prompt)
-
-          # Extract text from response
-          enforce_android_limit(extract_text_from_response(result))
+          translate_with_android_retries(text, target_locale) do |additional_instruction, user_content|
+            # Build prompt using inherited method (includes instructions, glossary, and text)
+            prompt = build_prompt(
+              user_content, source_locale, target_locale,
+              glossary_terms: glossary_terms,
+              platform: @params[:platform],
+              additional_instruction: additional_instruction
+            )
+
+            # Make API call
+            result = make_api_request(prompt)
+
+            # Extract text from response
+            extract_text_from_response(result)
+          end
         rescue StandardError => e
           UI.error "Gemini provider error: #{e.message}"
           nil

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/openai_provider.rb

@@ -81,37 +81,39 @@ module Fastlane
         # @param glossary_terms [Hash] Optional glossary { source_term => target_translation }
         # @return [String, nil] Translated text or nil on error
         def translate(text, source_locale, target_locale, glossary_terms: {})
-          # Build system instruction and user content separately for better results
-          system_instruction = build_system_instruction(
-            source_locale, target_locale,
-            glossary_terms: glossary_terms,
-            platform: @params[:platform]
-          )
-          user_content = text
-
-          # Build parameters hash with separate system and user messages
-          parameters = {
-            model: @params[:model_name] || DEFAULT_MODEL,
-            messages: [
-              { role: 'system', content: system_instruction },
-              { role: 'user', content: user_content }
-            ],
-            temperature: (@params[:temperature] || DEFAULT_TEMPERATURE).to_f
-          }
-
-          # Add service_tier if present
-          service_tier = @params[:service_tier].to_s.strip
-          parameters[:service_tier] = service_tier unless service_tier.empty?
-
-          # Make API call
-          response = @client.chat(parameters: parameters)
-
-          # Handle errors and extract text
-          if (error = response.dig('error', 'message'))
-            UI.error "OpenAI translation error: #{error}"
-            nil
-          else
-            enforce_android_limit(response.dig('choices', 0, 'message', 'content')&.strip)
+          translate_with_android_retries(text, target_locale) do |additional_instruction, user_content|
+            # Build system instruction and user content separately for better results
+            system_instruction = build_system_instruction(
+              source_locale, target_locale,
+              glossary_terms: glossary_terms,
+              platform: @params[:platform],
+              additional_instruction: additional_instruction
+            )
+
+            # Build parameters hash with separate system and user messages
+            parameters = {
+              model: @params[:model_name] || DEFAULT_MODEL,
+              messages: [
+                { role: 'system', content: system_instruction },
+                { role: 'user', content: user_content }
+              ],
+              temperature: (@params[:temperature] || DEFAULT_TEMPERATURE).to_f
+            }
+
+            # Add service_tier if present
+            service_tier = @params[:service_tier].to_s.strip
+            parameters[:service_tier] = service_tier unless service_tier.empty?
+
+            # Make API call
+            response = @client.chat(parameters: parameters)
+
+            # Handle errors and extract text
+            if (error = response.dig('error', 'message'))
+              UI.error "OpenAI translation error: #{error}"
+              nil
+            else
+              response.dig('choices', 0, 'message', 'content')&.strip
+            end
           end
         rescue StandardError => e
           UI.error "OpenAI provider error: #{e.message}"

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/translate_gpt_release_notes_helper.rb

@@ -1,19 +1,24 @@
 require 'fastlane_core/ui/ui'
 require_relative 'providers/provider_factory'
 require_relative 'glossary_loader'
+require_relative 'translation_evaluator'
 
 module Fastlane
   UI = FastlaneCore::UI unless Fastlane.const_defined?("UI")
 
   module Helper
     class TranslateGptReleaseNotesHelper
+      attr_reader :quality_checks
+
       def initialize(params)
         @params = params
+        @quality_checks = {}
+        @evaluator = TranslationEvaluator.new(params) if params[:jev_check]
         provider_name = params[:provider] || 'openai'
 
         # Validate provider selection
         unless Providers::ProviderFactory.valid_provider?(provider_name)
-          UI.warning "Unknown provider '#{provider_name}', falling back to OpenAI"
+          UI.important "Unknown provider '#{provider_name}', falling back to OpenAI"
           provider_name = 'openai'
         end
 
@@ -33,7 +38,7 @@ module Fastlane
       end
 
       # Request a translation from the configured provider
-      def translate_text(text, target_locale, _platform)
+      def translate_text(text, target_locale, platform)
         source_locale = @params[:master_locale]
         glossary_terms = @glossary_loader&.terms_for(text, target_locale) || {}
 
@@ -41,7 +46,26 @@ module Fastlane
           UI.message("Glossary: #{glossary_terms.size} terms matched for #{target_locale}")
         end
 
-        @provider.translate(text, source_locale, target_locale, glossary_terms: glossary_terms)
+        translation = @provider.translate(text, source_locale, target_locale, glossary_terms: glossary_terms)
+        if @evaluator && translation && !translation.to_s.strip.empty?
+          result = @evaluator.evaluate(text, translation, source_locale, target_locale, glossary_terms: glossary_terms, platform: platform)
+          @quality_checks[target_locale] = result
+          report_quality_check(target_locale, result)
+        end
+        translation
+      end
+
+      private
+
+      def report_quality_check(locale, result)
+        if result[:status] == 'unavailable'
+          UI.important("Jev #{locale}: check unavailable (#{result[:error]}); translation retained.")
+        elsif result[:warnings].any?
+          findings = result[:warnings].map { |name, probability| "#{name}=#{format('%.2f', probability)}" }.join(', ')
+          UI.important("Jev #{locale}: quality warning — #{findings}. Translation retained.")
+        else
+          UI.message("Jev #{locale}: no quality warnings detected.")
+        end
       end
 
     end

data/lib/fastlane/plugin/translate_gpt_release_notes/helper/translation_evaluator.rb

@@ -0,0 +1,105 @@
+require 'net/http'
+require 'json'
+
+module Fastlane
+  module Helper
+    # Optional reporting-only checks. Evaluation failures never discard a translation.
+    class TranslationEvaluator
+      ENDPOINT = 'https://api.typesafe.ai/v1/systemone'.freeze
+      DEFAULT_MODEL = 'jev-1.13.0'.freeze
+      QUESTIONS = {
+        'added_claim' => 'Does `translation` assert a feature, behavior, benefit, or fix not supported by `source`? Compare meaning across languages. Natural paraphrases and grammatical variants are not added claims. A direct reversal belongs to contradiction, not this check.',
+        'omission' => 'Does `translation` omit an entire material feature, fix, benefit, or availability statement from `source`? Concise paraphrases and summaries are allowed under `policy`; preserving all material points in fewer words is not an omission. Direct contradictions belong to the contradiction check.',
+        'contradiction' => 'Does `translation` make a statement with meaning directly contradicting `source`, such as reversing availability or saying a feature was removed when it was added? Compare meaning across languages.',
+        'wrong_language' => 'Is the prose in `translation` in a language other than the language specified by `target_locale`, or are full source-language sentences left untranslated? Product names and short technical terms are exempt.',
+        'glossary_error' => 'Does `translation` use a different UI feature name for a source term in `glossary` instead of the designated localized name? Allow capitalization, grammatical inflection, case endings, and agreement. Judge UI-name identity, not exact substring equality. If the term was omitted entirely, do not flag this check.'
+      }.freeze
+
+      def initialize(params)
+        @api_key = params[:typesafe_api_key].to_s.strip
+        @api_key = ENV['TYPESAFE_API_KEY'].to_s.strip if @api_key.empty?
+        @model = params[:jev_model] || DEFAULT_MODEL
+        @threshold = params[:jev_threshold] || 0.5
+        @timeout = params[:jev_timeout] || 10
+      end
+
+      def evaluate(source, translation, source_locale, target_locale, glossary_terms: {}, platform: nil)
+        return unavailable('TYPESAFE_API_KEY is not configured') if @api_key.to_s.strip.empty?
+
+        state = {
+          source: source, translation: translation, source_locale: source_locale,
+          target_locale: target_locale, glossary: glossary_terms, platform: platform,
+          policy: platform == 'android' ?
+            'Android requires at most 500 characters. Summarize concisely and omit minor wording, while retaining every material feature, fix, and availability claim.' :
+            'Preserve every material claim. Natural paraphrase and grammatical inflection are allowed.'
+        }
+        payload = {
+          model: @model, state: state,
+          questions: QUESTIONS.transform_values { |instructions| { type: 'noul', instructions: instructions } }
+        }
+        response = request(payload)
+        return unavailable("HTTP #{response.code}") unless response.is_a?(Net::HTTPSuccess)
+
+        parse_result(JSON.parse(response.body))
+      rescue StandardError => e
+        # Exception messages and API bodies can contain credentials or source text.
+        unavailable("request failed (#{e.class})")
+      end
+
+      private
+
+      def request(payload)
+        uri = URI(ENDPOINT)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request['Authorization'] = "Bearer #{@api_key}"
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(payload)
+
+        # Bound retries and delay so a checker outage does not stall a release lane.
+        response = nil
+        3.times do |attempt|
+          response = http.request(request)
+          break unless %w[429 529].include?(response.code) && attempt < 2
+
+          delay = response['Retry-After'].to_f
+          delay = 0.5 * (2**attempt) if delay <= 0
+          # Respect a longer server delay by ending this optional check instead.
+          break if delay > 2.0
+
+          sleep(delay)
+        end
+        response
+      end
+
+      def parse_result(result)
+        return unavailable('invalid response') unless result.is_a?(Hash) && result['model'].is_a?(String) && !result['model'].empty?
+
+        answers = result['answers']
+        return unavailable('invalid response') unless answers.is_a?(Hash)
+
+        probabilities = {}
+        QUESTIONS.each_key do |name|
+          answer = answers[name]
+          value = answer['noul'] if answer.is_a?(Hash)
+          unless answer.is_a?(Hash) && answer['type'] == 'noul' && value.is_a?(Numeric) && value.finite? && value.between?(0, 1)
+            return unavailable('invalid response')
+          end
+          probabilities[name] = value
+        end
+        {
+          status: 'checked', model: result['model'], probabilities: probabilities,
+          warnings: probabilities.select { |_name, probability| probability >= @threshold }
+        }
+      end
+
+      def unavailable(reason)
+        { status: 'unavailable', error: reason }
+      end
+    end
+  end
+end

data/lib/fastlane/plugin/translate_gpt_release_notes/version.rb

@@ -1,5 +1,5 @@
 module Fastlane
   module TranslateGptReleaseNotes
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/fastlane/plugin/translate_gpt_release_notes.rb

@@ -4,7 +4,9 @@ module Fastlane
   module TranslateGptReleaseNotes
     # Return all .rb files inside the "actions" and "helper" directory
     def self.all_classes
-      Dir[File.expand_path('**/{actions,helper}/*.rb', File.dirname(__FILE__))]
+      Dir[File.expand_path('**/{actions,helper}/*.rb', File.dirname(__FILE__))].reject do |path|
+        File.basename(path).include?('.sync-conflict-')
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fastlane-plugin-translate_gpt_release_notes
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Anton Karliner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-openai
@@ -240,6 +240,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/fastlane/plugin/translate_gpt_release_notes.rb
@@ -253,6 +254,7 @@ files:
 - lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/openai_provider.rb
 - lib/fastlane/plugin/translate_gpt_release_notes/helper/providers/provider_factory.rb
 - lib/fastlane/plugin/translate_gpt_release_notes/helper/translate_gpt_release_notes_helper.rb
+- lib/fastlane/plugin/translate_gpt_release_notes/helper/translation_evaluator.rb
 - lib/fastlane/plugin/translate_gpt_release_notes/version.rb
 homepage: https://github.com/antonkarliner/fastlane-plugin-translate_gpt_release_notes
 licenses: