@dialpad/i18n 1.25.7 → 1.27.0

package/docs/README.md

@@ -7,8 +7,8 @@
 This package contains all the logic needed to handle i18n for a Dialpad
 application extending from the common logic existing in the base locale manager
 that you can find about on the
-[i18n-services documentation](../../i18n-services/docs/README.md), based on
-different bundle sources.
+[i18n-goblin-services documentation](../../i18n-goblin-services/docs/README.md),
+based on different bundle sources.
 
 ## How it works
 
@@ -696,17 +696,55 @@ Each screenshot should contain visual information of where the translation can
 be found in the app with enough context to be easily located. If other dev looks
 at the screenshot they should be able to locate it fairly easily in your app.
 
-There should be one screenshot per each translation key on each `.ftl` file. You
-can reuse the same screenshot for multiple keys, but each file will correspond
-to one key, so you must make one copy for each translation key. The screenshot
-filename will be `{translationKeyHere}.png`. We only support `.png` images for
-now.
+By default each translation key needs its own `{translationKey}.png`. When
+several keys share a view (e.g. a modal) you can point them at a single
+screenshot instead of duplicating it — either inline with the `@screenshot:`
+marker (`# @screenshot: modal.png` per key, or a block
+`## @screenshot: modal.png` group comment that scopes every following key until
+the next `##`), or via the config `groups` below. The marker value is a bare
+filename in the sibling `context-screenshots/` dir (extension optional). We only
+support `.png` images for now.
 
 There is a PR check which will fail if any translation key is missing its
-corresponding screenshot. There is an exception list for paths that should be
-ignored by this check. Avoid using it unless it's completely necessary. If you
-strictly need to use it, remember to mention in your commit message why you are
-using it.
+corresponding screenshot. Keys and paths can be opted out through three
+mechanisms (any one is sufficient — they are additive, with no precedence):
+
+**1. Inline comment marker** — add `# @i18n-screenshot-ignore` directly above a
+message (no blank line, space after `#` required), or a block
+`## @i18n-screenshot-ignore` group comment to opt out every key that follows it
+until the next `##`:
+
+```fluent
+# @i18n-screenshot-ignore
+my-dynamic-key = Some value that changes at runtime
+```
+
+**2. Co-located config file** — create an optional `i18n-screenshots.config`
+sibling to your `.ftl` file (absence is fine, never fails the check). It can be
+JSON or a `.js`/`.ts` module (default export):
+
+```jsonc
+// i18n-screenshots.config.json
+{
+  "excludeKeys": ["my-dynamic-key"], // exact key names to skip
+  "excludePaths": ["legacy/**"], // globs relative to this dir to skip wholesale
+  "groups": { "modal.png": ["modal-title", "modal-save"] }, // share one screenshot
+}
+```
+
+```ts
+// i18n-screenshots.config.ts — same shape, loaded via Node type-stripping
+export default {
+  groups: { 'modal.png': ['modal-title', 'modal-save'] },
+};
+```
+
+Inline `@screenshot:` markers take priority over config `groups` for the same
+key.
+
+**3. Built-in exception list** — a hardcoded list in the shared package covers
+projects that were already excluded before the config existed. Avoid adding to
+it; use a co-located config in your app repo instead.
 
 These screenshots will be located in a directory called `context-screenshots`
 sibling to each `.ftl` file in your project. If you have an `.ftl` file, it
@@ -722,4 +760,3 @@ github action when a PR to main is merged.
 - [I18n best practices](https://localization.blog/2022/05/16/i18n-best-practices-keep-it-together/)
 - [i18n-goblin-core docs](../../i18n-goblin-core/docs/README.md)
 - [i18n-goblin-services docs](../../i18n-goblin-services/docs/README.md)
-- [i18n-services docs (deprecated)](../../i18n-services/docs/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dialpad/i18n",
-  "version": "1.25.7",
+  "version": "1.27.0",
   "private": false,
   "description": "Internationalization library for Vue 3 apps using Mozilla's Fluent syntax, with locale management, translation bundle loading, and CLI tools for translation workflows",
   "keywords": [
@@ -23,7 +23,7 @@
   ],
   "dependencies": {
     "@dialpad/i18n-goblin-core": "1.2.1",
-    "@dialpad/i18n-goblin-services": "1.4.0"
+    "@dialpad/i18n-goblin-services": "1.6.0"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "~6.0.5",