Refactor metadata PO files generation

CHANGELOG.md

@@ -6,21 +6,30 @@
 
 ### Breaking Changes
 
-_None_
+- Generated PO files now have entries sorted **alphabetically by `msgctxt`** for deterministic output. This may affect tests or tooling that depend on a specific entry order. [#684]
+- Existing translator comments (`#.` lines) in PO files will be **lost** when regenerating unless explicitly added to the `source_files` parameter. See `MIGRATION.md` for instructions on preserving comments. [#684]
 
 ### New Features
 
-_None_
+- Add `commit_changes` option to `gp_update_metadata_source` to optionally commit changes after updating the PO file. [#684]
+- Add support for translator comments in `gp_update_metadata_source` via a new hash format for `source_files` entries: `{ path: 'file.txt', comment: 'translators: ...' }`. Simple string paths are still supported for entries without comments. [#684]
 
 ### Bug Fixes
 
 _None_
 
 ### Internal Changes
 
+- Consolidate PO file update logic on `gp_update_metadata_source` action. [#684]
+- Remove legacy `MetadataBlock` classes replaced by the new `PoFileGenerator`. [#684]
 - Improved efficiency and refined the logs of the `promo_screenshots` action. [#685]
 - Updated minimum Fastlane requirement to 2.231.0. [#685]
 
+### Deprecated
+
+- `an_update_metadata_source` action is deprecated; use `gp_update_metadata_source` instead. The API is unchanged, but generated PO files will have different ordering and comments will be lost unless migrated to use the new comment format. [#684]
+- `ios_update_metadata_source` action is deprecated; use `gp_update_metadata_source` with `commit_changes: true` instead. The API is unchanged, but generated PO files will have different ordering and comments will be lost unless migrated to use the new comment format. [#684]
+
 ## 13.8.1
 
 ### Bug Fixes

Gemfile.lock

@@ -7,6 +7,7 @@ PATH
       chroma (= 0.2.0)
       diffy (~> 3.3)
       fastlane (~> 2.231)
+      gettext (~> 3.5)
       git (~> 1.3)
       google-cloud-storage (~> 1.31)
       java-properties (~> 0.3.0)
@@ -22,7 +23,10 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (3.0.8)
+    CFPropertyList (3.0.7)
+      base64
+      nkf
+      rexml
     abbrev (0.1.2)
     activesupport (7.2.2.1)
       base64
@@ -36,37 +40,37 @@ GEM
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
-    addressable (2.8.8)
-      public_suffix (>= 2.0.2, < 8.0)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     algoliasearch (1.27.5)
       httpclient (~> 2.8, >= 2.8.3)
       json (>= 1.5.1)
     artifactory (3.0.17)
     ast (2.4.2)
     atomos (0.1.3)
     aws-eventstream (1.4.0)
-    aws-partitions (1.1206.0)
-    aws-sdk-core (3.241.4)
+    aws-partitions (1.1196.0)
+    aws-sdk-core (3.240.0)
       aws-eventstream (~> 1, >= 1.3.0)
       aws-partitions (~> 1, >= 1.992.0)
       aws-sigv4 (~> 1.9)
       base64
       bigdecimal
       jmespath (~> 1, >= 1.6.1)
       logger
-    aws-sdk-kms (1.121.0)
-      aws-sdk-core (~> 3, >= 3.241.4)
+    aws-sdk-kms (1.118.0)
+      aws-sdk-core (~> 3, >= 3.239.1)
       aws-sigv4 (~> 1.5)
-    aws-sdk-s3 (1.212.0)
-      aws-sdk-core (~> 3, >= 3.241.4)
+    aws-sdk-s3 (1.208.0)
+      aws-sdk-core (~> 3, >= 3.234.0)
       aws-sdk-kms (~> 1)
       aws-sigv4 (~> 1.5)
     aws-sigv4 (1.12.1)
       aws-eventstream (~> 1, >= 1.0.2)
     babosa (1.0.4)
     base64 (0.2.0)
     benchmark (0.4.0)
-    bigdecimal (4.0.1)
+    bigdecimal (3.1.9)
     buildkit (1.6.1)
       sawyer (>= 0.6)
     buildkite-test_collector (2.9.0)
@@ -162,6 +166,7 @@ GEM
     dotenv (2.8.1)
     drb (2.2.1)
     emoji_regex (3.2.3)
+    erubi (1.13.1)
     escape (0.0.4)
     ethon (0.16.0)
       ffi (>= 1.15.0)
@@ -178,16 +183,16 @@ GEM
       faraday-rack (~> 1.0)
       faraday-retry (~> 1.0)
       ruby2_keywords (>= 0.0.4)
-    faraday-cookie_jar (0.0.8)
+    faraday-cookie_jar (0.0.7)
       faraday (>= 0.8.0)
-      http-cookie (>= 1.0.0)
+      http-cookie (~> 1.0.0)
     faraday-em_http (1.0.0)
-    faraday-em_synchrony (1.0.1)
+    faraday-em_synchrony (1.0.0)
     faraday-excon (1.1.0)
     faraday-http-cache (2.5.1)
       faraday (>= 0.8)
     faraday-httpclient (1.0.1)
-    faraday-multipart (1.2.0)
+    faraday-multipart (1.1.0)
       multipart-post (~> 2.0)
     faraday-net_http (1.0.2)
     faraday-net_http_persistent (1.2.0)
@@ -248,8 +253,15 @@ GEM
     fastlane-sirp (1.0.0)
       sysrandom (~> 1.0)
     ffi (1.17.1)
+    forwardable (1.3.3)
     fourflusher (2.3.1)
     fuzzy_match (2.0.4)
+    gettext (3.5.1)
+      erubi
+      locale (>= 2.0.5)
+      prime
+      racc
+      text (>= 1.3.0)
     gh_inspector (1.1.3)
     git (1.19.1)
       addressable (~> 2.8)
@@ -300,28 +312,29 @@ GEM
       concurrent-ruby (~> 1.0)
     java-properties (0.3.0)
     jmespath (1.6.2)
-    json (2.18.0)
-    jwt (2.10.2)
+    json (2.10.2)
+    jwt (2.10.1)
       base64
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
-    logger (1.7.0)
+    locale (2.1.4)
+    logger (1.6.6)
     method_source (0.9.2)
     mini_magick (4.13.2)
     mini_mime (1.1.5)
     mini_portile2 (2.8.9)
     minitest (5.25.5)
     molinillo (0.8.0)
-    multi_json (1.19.1)
+    multi_json (1.15.0)
     multipart-post (2.4.1)
     mutex_m (0.3.0)
     nanaimo (0.4.0)
     nap (1.1.0)
-    naturally (2.3.0)
+    naturally (2.2.1)
     netrc (0.11.0)
     nkf (0.2.0)
     nokogiri (1.18.9)
@@ -333,14 +346,17 @@ GEM
       sawyer (~> 0.9)
     open4 (1.3.4)
     options (2.3.2)
-    optparse (0.8.1)
+    optparse (0.6.0)
     os (1.1.4)
     parallel (1.26.3)
     parser (3.3.7.1)
       ast (~> 2.4.1)
       racc
     pkg-config (1.6.0)
     plist (3.7.2)
+    prime (0.1.3)
+      forwardable
+      singleton
     progress_bar (1.3.4)
       highline (>= 1.6)
       options (~> 2.3.0)
@@ -351,7 +367,7 @@ GEM
     public_suffix (4.0.7)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.2.1)
     rake-compiler (1.2.9)
       rake
     rchardet (1.9.0)
@@ -361,7 +377,7 @@ GEM
       trailblazer-option (>= 0.1.1, < 0.2.0)
       uber (< 0.2.0)
     retriable (3.1.2)
-    rexml (3.4.4)
+    rexml (3.4.2)
     rmagick (5.5.0)
       observer (~> 0.1)
       pkg-config (~> 1.4)
@@ -405,10 +421,10 @@ GEM
       faraday (>= 0.17.3, < 3)
     securerandom (0.4.1)
     security (0.1.5)
-    signet (0.21.0)
+    signet (0.19.0)
       addressable (~> 2.8)
       faraday (>= 0.17.5, < 3.a)
-      jwt (>= 1.5, < 4.0)
+      jwt (>= 1.5, < 3.0)
       multi_json (~> 1.10)
     simctl (1.6.10)
       CFPropertyList
@@ -418,10 +434,12 @@ GEM
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
+    singleton (0.3.0)
     sysrandom (1.0.5)
     terminal-notifier (2.0.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
+    text (1.3.1)
     trailblazer-option (0.1.2)
     tty-cursor (0.7.1)
     tty-screen (0.8.2)

MIGRATION.md

@@ -1,5 +1,72 @@
 # Migration Instructions for Major Releases
 
+## From 13.x to 14.0.0
+
+### Metadata Source Actions
+
+The `ios_update_metadata_source` and `an_update_metadata_source` actions are now deprecated. Use `gp_update_metadata_source` instead:
+
+```ruby
+# Before (iOS)
+ios_update_metadata_source(
+  po_file_path: 'path/to/AppStoreStrings.pot',
+  source_files: { app_name: 'path/to/name.txt' },
+  release_version: '1.0'
+)
+
+# Before (Android)
+an_update_metadata_source(
+  po_file_path: 'path/to/PlayStoreStrings.po',
+  source_files: { app_name: 'path/to/name.txt' },
+  release_version: '1.0'
+)
+
+# After (both platforms)
+gp_update_metadata_source(
+  po_file_path: 'path/to/AppStoreStrings.pot',
+  source_files: { app_name: 'path/to/name.txt' },
+  release_version: '1.0',
+  commit_changes: true  # Set to true if you want auto-commit (like ios_update_metadata_source did)
+)
+```
+
+### Translator Comments in PO Files
+
+**Important:** The new `gp_update_metadata_source` action regenerates PO files from scratch. Any existing translator comments (lines starting with `#.`) in your PO files will be **lost** unless you explicitly add them to your `source_files` hash.
+
+To preserve translator comments, update your `source_files` to use the new hash format with `:path` and `:comment` keys:
+
+```ruby
+# Before (comments in PO file will be lost)
+source_files: {
+  app_store_subtitle: 'path/to/subtitle.txt',
+  app_store_keywords: 'path/to/keywords.txt'
+}
+
+# After (comments are preserved in generated PO)
+source_files: {
+  app_store_subtitle: {
+    path: 'path/to/subtitle.txt',
+    comment: 'translators: Limit to 30 characters!'
+  },
+  app_store_keywords: {
+    path: 'path/to/keywords.txt',
+    comment: "translators: Delimit with commas.\nLimit to 100 characters."
+  },
+  # Simple paths still work for entries without comments
+  app_name: 'path/to/name.txt'
+}
+```
+
+**Migration steps:**
+1. Check your existing `.po`/`.pot` files for any `#.` comment lines
+2. Extract those comments and add them to the `source_files` hash in your Fastfile
+3. Replace `ios_update_metadata_source`/`an_update_metadata_source` with `gp_update_metadata_source`
+
+### PO File Entry Ordering
+
+Generated PO files now have entries sorted **alphabetically by `msgctxt`**. This ensures deterministic output across runs. If you have tests or tooling that depend on a specific entry order, they may need to be updated.
+
 ## From 12.x to 13.0.0
 
 - The `prototype_build_details_comment` action have been updated to work with Firebase App Distribution instead of App Center [#630].

fastlane-plugin-wpmreleasetoolkit.gemspec

@@ -5,12 +5,12 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'fastlane/plugin/wpmreleasetoolkit/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = 'fastlane-plugin-wpmreleasetoolkit'
+  spec.name          = Fastlane::Wpmreleasetoolkit::NAME
   spec.version       = Fastlane::Wpmreleasetoolkit::VERSION
   spec.author        = 'Automattic'
   spec.email         = 'mobile@automattic.com'
 
-  spec.summary       = 'GitHub helper functions'
+  spec.summary       = 'Fastlane plugin for release automation'
   spec.homepage      = 'https://github.com/wordpress-mobile/release-toolkit'
   spec.license       = 'MIT'
 
@@ -31,6 +31,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'chroma', '0.2.0'
   spec.add_dependency 'diffy', '~> 3.3'
   spec.add_dependency 'fastlane', '~> 2.231'
+  spec.add_dependency 'gettext', '~> 3.5'
   spec.add_dependency 'git', '~> 1.3'
   spec.add_dependency 'java-properties', '~> 0.3.0'
   spec.add_dependency 'nokogiri', '~> 1.11'