[Tooling] Localization README update (#795)

* Update README to reflect sync_localization lane and workflow update

* Use same Buildkite annotation context on sync_localization lane

* Add documentation about new localization PRs replacing the previous ones

Co-authored-by: Olivier Halligon <[email protected]>

* Expand documentation on automatic PO file upload

Co-authored-by: Olivier Halligon <[email protected]>

* Remove redundant description of automation steps

* Add Mermaid graph of the localization workflow

* Update README to clarify behavior when there's a previous localization PR

Co-authored-by: Olivier Halligon <[email protected]>

* Add descriptive info linked to the Mermaid chart

* Change order to group workflow description sections

---------

Co-authored-by: Olivier Halligon <[email protected]>

Author: iangmaia

fastlane/Fastfile

@@ -281,7 +281,7 @@ lane :sync_localization do
 
     if is_ci
       buildkite_annotate(
-        context: 'localization-sync-no-changes',
+        context: 'localization-sync',
         style: 'info',
         message: 'No localization changes to commit. No PR was created.'
       )
@@ -317,7 +317,7 @@ lane :sync_localization do
 
   if is_ci && pr_result
     buildkite_annotate(
-      context: 'localization-sync-pr',
+      context: 'localization-sync',
       style: 'info',
       message: "Localization Sync Pull Request: #{pr_result}"
     )

wp_localization/README.md

@@ -15,25 +15,94 @@ _Note that we have to commit the `glotpress/en-US.pot` file here because that fi
 
 ## Workflow for Developers
 
-### Automated Daily Sync
+### Automated Nightly Sync
 
 The localization process runs automatically every night via a Buildkite pipeline (`.buildkite/nightly.yml`). This automated job:
 
 1. **Generates the source en-US PO file** from `localization/en-US/main.ftl` and commits it to `glotpress/en-US.pot`
 2. **Downloads latest translations** from GlotPress for all supported locales as PO files
 3. **Converts downloaded PO files to Fluent format** and updates the corresponding `localization/*/main.ftl` files
-4. **Commits the updated translation files** to the repository
+4. **Creates a Pull Request** targeting `trunk` with the updated translation files and the updated original en-US PO file in the repository.
+   - If a previous localization sync Pull Request was still open at the time the nightly sync happens, that previous Pull Request will be closed and a new one will be opened with the latest translations to take its place.
+
+Once you merge the Pull Request into `trunk`, the updated `glotpress/en-US.pot` file will be picked up by a wpcom job to import it into GlotPress, so that translators can start working on the new strings.
 
 This means that translation updates happen automatically without developer intervention.
 
 ### Adding New Localization Strings
 
-1. **Add strings to the source file**: Edit `wp_localization/localization/en-US/main.ftl` to add or update localization strings.
-
-2. **The automated nightly job will handle the rest**: The next nightly run will automatically:
-   - Convert your changes to PO format (`glotpress/en-US.pot`)
-   - Commit the updated source file
-   - Upload to GlotPress via the wpcom cron job
+To add or update new localizable strings to the project, just edit `wp_localization/localization/en-US/main.ftl` to add or update them, using the English copy.
+
+[The "Automated Nightly Sync" described above](#automated-nightly-sync) will take care of the rest. In particular:
+
+* Once your `en-US/main.ftl` file has landed into `trunk`, it will be read by the "Automated Nightly Sync" job on its next run (2), to generate a `en-US.pot` file (which will later be imported in GlotPress (6 & 7))
+* That automation will also use the occasion to download latest translations from GlotPress (3), then create a Pull Request (4) containing both this generated `en-US.pot` from (2) and the new `*/main.ftl` translations from (3)
+* After you merge that Pull Request (5), the wpcom job will be able to later import the `en-US.pot` file with the latest originals to GlotPress (6 & 7)
+* Note that you'll only get the translations from the new string after 2 cycles of the Automated Nightly Sync: the first one (2–7) will ensure the new strings you added in (1) will make its way to GlotPress for translators to start working on it, while the 2nd run (9–14) will bring those translations from GlotPress to trunk after the translators had time to work on them.
+
+## Localization Process Flow
+
+Here's a visual representation of the typical localization workflow:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Dev
+    participant Git
+    participant ANS as Automated Nightly Sync<br/>(Buildkite Job)
+    participant GlotPress
+    participant wpcom as wpcom cron job
+
+    Dev->>Git: Add new string "A" to `en-US/main.ftl` and commit to trunk
+
+    loop Nightly Sync (Run 1)
+        activate ANS
+        Git-->>ANS: Read `en-US/main.ftl` from trunk<br/>(existing strings + "A")
+        note over ANS: Generate `en-US.pot` with all strings including "A"
+        GlotPress-->>ANS: Download `.po` translations for existing strings
+        note over ANS: Convert `.po` to `*/main.ftl` files
+        ANS->>Git: Create Pull Request targeting trunk
+        note right of Git: PR contains updated `en-US.pot` (with new string "A")<br/>and updated `*/main.ftl` files (existing translations only)
+        deactivate ANS
+    end
+
+    Dev->>Git: Merge Pull Request into trunk
+    note right of Git: `en-US.pot` with string "A" now available
+
+    activate wpcom
+    Git-->>wpcom: wpcom cron picks up updated `en-US.pot` from trunk
+    wpcom->>GlotPress: Import new `en-US.pot` with string "A"
+    deactivate wpcom
+    
+    activate GlotPress
+    note over GlotPress: Translators work on new string "A"
+    deactivate GlotPress
+
+    Dev->>Git: Add new string "B" to `en-US/main.ftl` and commit to trunk
+
+    loop Nightly Sync (Run 2)
+        activate ANS
+        Git-->>ANS: Read `en-US/main.ftl` from trunk<br/>(existing + "A" + "B")
+        note over ANS: Generate `en-US.pot` with all strings including "A" and "B"
+        GlotPress-->>ANS: Download `.po` translations (now includes "A" translations)
+        note over ANS: Convert `.po` to `*/main.ftl` files
+        ANS->>Git: Create Pull Request targeting trunk
+        note right of Git: PR contains updated `en-US.pot` (with new string "B")<br/>and updated `*/main.ftl` files (including "A" translations)
+        deactivate ANS
+    end
+
+    Dev->>Git: Merge Pull Request into trunk
+    note right of Git: Translations for string "A" now in trunk
+
+    activate wpcom
+    Git-->>wpcom: wpcom cron picks up updated `en-US.pot` from trunk
+    wpcom->>GlotPress: Import new `en-US.pot` with string "B"
+    deactivate wpcom
+    
+    activate GlotPress
+    note over GlotPress: Translators work on new string "B"
+    deactivate GlotPress
+```
 
 ### Manual Operations (Optional)
 
@@ -49,6 +118,11 @@ bundle exec fastlane generate_source_po_file
 bundle exec fastlane download_translations
 ```
 
+**Runs both lanes above and creates a new Pull Request with the changes targeting `trunk`:**
+```bash
+bundle exec fastlane sync_localization
+```
+
 ### Helper Lanes
 
 - **`download_po_files_from_glotpress`**: Downloads PO files for all supported locales
@@ -58,5 +132,5 @@ bundle exec fastlane download_translations
 
 - **Fluent format**: Uses [Project Fluent](https://projectfluent.org/) for localization files
 - **PO format**: Standard [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) format used by GlotPress
-- **Conversion tool**: Uses the [fluent-tools](https://github.com/Automattic/fluent-rust-tools) Ruby gem for format conversion
+- **Conversion tool**: Uses the [fluent-tools](https://github.com/Automattic/fluent-rust-tools) CLI and Ruby Gem for format conversion
 - **GlotPress integration**: Downloads translations from `https://translate.wordpress.com/projects/mobile/wordpress-rs`