flutter-localization: sync ARB changes with poe2arb upload

plugins/flutter-localization/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "flutter-localization",
   "displayName": "Flutter Localization",
   "description": "LeanCode Flutter localization guidance for ARB, POEditor, and l10n(context) workflows.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": {
     "name": "LeanCode"
   },

plugins/flutter-localization/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.2.0
+
+- `poe2arb-workflow` and the localization conventions (`flutter-localization-usage/references/localization.md`) use `poe2arb upload` to sync ARB changes to POEditor, replacing `poe2arb seed`, which is now only for setting up a fresh project.
+- The workflow pulls with `poe2arb poe` before editing ARBs, previews with `poe2arb upload --dry-run`, requires poe2arb 2.6.0 or newer, and passes `--force` only after the user confirms the listed term deletions.

plugins/flutter-localization/README.md

@@ -8,7 +8,7 @@ Contains the localization rule and workflow:
 
 - `skills/flutter-localization-usage/references/localization.md`: localization conventions
 - `skills/flutter-localization-usage/SKILL.md`: entry point for this plugin
-- `skills/poe2arb-workflow/SKILL.md`: workflow for ARB updates, `flutter gen-l10n`, and `poe2arb seed`
+- `skills/poe2arb-workflow/SKILL.md`: workflow for ARB updates, `flutter gen-l10n`, and syncing with POEditor via `poe2arb poe` and `poe2arb upload`
 
 ## Example usage
 

plugins/flutter-localization/skills/flutter-localization-usage/SKILL.md

@@ -16,7 +16,7 @@ description: Explain what the `flutter-localization` plugin does and how to use
 ## What this plugin does
 
 - Covers ARB-based translation conventions for LeanCode Flutter projects.
-- Explains `l10n(context)` usage in widgets and the POEditor plus `poe2arb` sync flow.
+- Explains `l10n(context)` usage in widgets and the POEditor plus `poe2arb` sync flow (`poe2arb poe` to pull, `poe2arb upload` to push).
 - Keeps localization boundaries aligned with LeanCode rules.
 
 ## How to use it
@@ -31,6 +31,7 @@ description: Explain what the `flutter-localization` plugin does and how to use
 - "Add translations for the new booking status labels."
 - "Review this app's localization usage and `l10n(context)` usage."
 - "Walk me through the `poe2arb` sync flow."
+- "Push my ARB changes to POEditor with `poe2arb upload`."
 
 ## Reach for these assets
 

plugins/flutter-localization/skills/flutter-localization-usage/references/localization.md

@@ -6,4 +6,6 @@ All translations are stored in package specific `app_<language_code>.arb` files.
 - Always use translations in presentation layer (inside `Widgets`). Access translations as `final s = l10n(context);`
 - Never use translations outside presentation layer. If needed map message models to localized value in presentation layer
 - Always run `flutter gen-l10n` if any translation was added
-- Always run `poe2arb seed` if any translation was added to upload them to `POEditor`
+- Always run `poe2arb poe` before editing ARB files so they hold the latest translations from `POEditor`
+- Always run `poe2arb upload` if any translation was added, changed, or removed to sync them to `POEditor`. Run `poe2arb upload --dry-run` first and never pass `--force` without the user's confirmation
+- Use `poe2arb seed` only to set up a fresh `POEditor` project

plugins/flutter-localization/skills/poe2arb-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: poe2arb-workflow
-description: Handle Flutter localization workflows backed by POEditor and poe2arb. Use when adding translations, syncing ARB files with POEditor, or when the user mentions poe2arb, POEditor, seed, or flutter gen-l10n.
+description: Handle Flutter localization workflows backed by POEditor and poe2arb. Use when adding, changing, or removing translations, syncing ARB files with POEditor, or when the user mentions poe2arb, POEditor, upload, seed, or flutter gen-l10n.
 ---
 
 # POEditor and poe2arb Workflow
@@ -15,13 +15,28 @@ Keep the localization workflow aligned with the shared localization rules.
 - Access translations as `final s = l10n(context);`
 - If other layers need localized text, map message models to localized values in the presentation layer.
 
-## Workflow when adding translations
+## Commands
 
-1. Add the required translation to all relevant `app_<language_code>.arb` files.
-2. Run `flutter gen-l10n`.
-3. Run `poe2arb seed` to upload the added translation to POEditor.
+All commands read the same configuration (`l10n.yaml`, `POEDITOR_TOKEN`, flags) and run from the package directory that holds `l10n.yaml`.
+
+- `poe2arb poe` downloads translations from POEditor into the local ARB files. A read-only token is enough.
+- `poe2arb upload` pushes local ARB changes to POEditor: adds new terms, overwrites existing translations and term definitions, and adds missing languages. It needs a token with write access and poe2arb 2.6.0 or newer.
+- `poe2arb seed` is only for setting up a fresh POEditor project from existing ARB files. Do not use it to sync ongoing changes; use `upload`.
+
+`upload` is destructive: POEditor ends up matching the local ARBs, so any translation edited in POEditor but not pulled locally is overwritten. With `--force` it also permanently deletes terms that exist in POEditor but not in the template ARB. Term deletion is scoped to `poeditor-term-prefix`, so packages sharing one POEditor project under a different prefix are unaffected.
+
+## Workflow when changing translations
+
+1. Check that `poe2arb version` is 2.6.0 or newer. If it is older, ask the user to upgrade poe2arb before syncing.
+2. Run `poe2arb poe` before editing the ARB files, so they hold the latest translations from POEditor and the upload does not overwrite translators' work.
+3. Add, change, or remove the translation in all relevant `app_<language_code>.arb` files.
+4. Run `flutter gen-l10n`.
+5. Run `poe2arb upload --dry-run` and show the user the summary: terms to add and remove, per-language added/updated/unchanged counts, and languages that would be created. Check that it matches the intended change; unexpected updates usually mean the ARBs were not pulled first.
+6. Run `poe2arb upload`.
+   - If it aborts because terms exist in POEditor but not locally, show the listed terms to the user. Re-run with `--force` only after the user explicitly confirms those terms should be deleted from POEditor; otherwise restore the missing terms locally or stop.
 
 ## Output expectations
 
 - If asked to change translations, update the ARB files first.
-- Clearly say whether `flutter gen-l10n` and `poe2arb seed` were run or still need to be run.
+- Clearly say which of `poe2arb poe`, `flutter gen-l10n`, `poe2arb upload --dry-run`, and `poe2arb upload` were run or still need to be run.
+- Never pass `--force` without the user's explicit confirmation of the listed deletions, because deleted terms take all their translations with them.