@vtex/faststore-plugin-buyer-portal 2.0.13 → 2.0.14

package/docs/i18n/i18n-messages-format.md

@@ -0,0 +1,391 @@
+# i18n Message Catalog Format
+
+> Reference document describing the structure and conventions used by the
+> internationalization (i18n) message catalogs in `src/messages/*.json`. This
+> document is intended to be reused as **agent context** in other projects to:
+>
+> 1. Extract user-facing strings from a codebase, and
+> 2. Produce message catalog files that follow the exact same format.
+
+---
+
+## 1. Overview
+
+The project uses [`react-intl`](https://formatjs.io/docs/react-intl/) (FormatJS).
+All translatable strings live in flat JSON files under `src/messages/`, one file
+per locale. Today the project ships:
+
+```
+src/messages/
+├── en-US.json   ← source / fallback locale
+└── pt-BR.json   ← target locale
+```
+
+Both files share the **exact same set of keys**. The values are the localized
+strings.
+
+## 2. File Format
+
+Each catalog is a **flat JSON object** (one level deep). Keys are
+dot-separated namespaces; values are the localized strings.
+
+```json
+{
+  "shared.buttons.save": "Save",
+  "shared.buttons.cancel": "Cancel",
+  "addresses.forms.country": "Country",
+  "addresses.validation.streetRequired": "Street Address is required",
+  "users.delete.question": "Permanently delete {userName}?"
+}
+```
+
+> Important: Do **NOT** use nested objects (e.g. `{ "shared": { "buttons": {…} } }`).
+> The format is intentionally flat — `react-intl` looks up messages by the full
+> dotted string id.
+
+### Formatting rules
+
+- File is UTF-8 JSON, ends with a single trailing newline.
+- Two-space indentation.
+- Keys are quoted strings; the entire id (including dots) is a single key.
+- All catalogs (locales) MUST share the same set of keys.
+- Strings can span multiple lines in source if needed; tooling preserves them
+  as a single string. Keep them on a single line whenever practical.
+
+## 3. Key Naming Convention
+
+Each id is composed of **2 to 4 dot-separated segments**:
+
+```
+<feature>.<group>[.<sub-group>].<name>
+```
+
+| Segment | Description | Casing |
+|---------|-------------|--------|
+| `feature` | Top-level feature/domain (e.g. `addresses`, `users`, `shared`) | `camelCase` |
+| `group` | Logical grouping inside the feature (e.g. `buttons`, `forms`, `toast`, `drawers`) | `camelCase` |
+| `sub-group` *(optional)* | Further specialization, e.g. component name, sub-flow, action | `camelCase` |
+| `name` | The specific string identifier | `camelCase` |
+
+Examples:
+
+```
+shared.buttons.save                              → 3 segments
+addresses.validation.streetRequired              → 3 segments
+addresses.components.deleteAddress.title         → 4 segments (sub-group = component)
+users.createWithUsername.sharedEmailBody1        → 3 segments (sub-group baked into group)
+buyingPolicies.criteria.spending.orderValueGtX   → 4 segments
+```
+
+### Casing notes
+
+- The codebase is **predominantly camelCase** for all segments.
+- A small amount of legacy keys use kebab-case for the feature segment
+  (`buying-policies.*`, `credit-cards.*`, `b2b-agent.*`, `org-units.*`). These
+  duplicate the camelCase versions (`buyingPolicies.*`, `creditCards.*`, etc.)
+  and exist for backwards compatibility. **New keys MUST use camelCase.**
+
+## 4. Top-Level Feature Namespaces
+
+The `feature` segment maps to a feature folder under `src/features/` (or to a
+cross-cutting concern). The catalog observed in this project uses the namespaces
+below — when introducing new strings, prefer reusing one of these instead of
+inventing a new namespace.
+
+| Namespace | Scope |
+|-----------|-------|
+| `shared` | Cross-cutting strings reused everywhere (buttons, generic labels, errors, generic drawer copy, pagination, validation, region selector, etc.) |
+| `addresses` | Addresses feature (forms, locations, recipients, address settings) |
+| `roles` | Roles & permissions (role names, permission labels & descriptions) |
+| `orgUnits` | Organizational units feature (CRUD, hierarchy, authentication setup) |
+| `orgUnitDetails` | Org-unit details page (links, footer, action menus) |
+| `phone` | Phone-input shared component (countries, errors, labels) |
+| `buyingPolicies` | Buying policies feature (CRUD, criteria, workflow, actions) |
+| `creditCards` | Credit cards feature (CRUD, settings, toasts) |
+| `paymentMethods` | Payment methods feature (CRUD, settings, removal flow) |
+| `productAssortment` | Product assortment / collections feature |
+| `budgets` | Budgets feature (CRUD, allocations, notifications, success screen) |
+| `users` | Users feature (CRUD, reset password, reassign org unit, username flow) |
+| `customFields` | Generic custom-field settings/toasts (PO numbers, cost centers, releases) |
+| `contracts` | Contracts feature |
+| `profile` | Profile feature |
+| `layouts` | Strings owned by page layout components (titles, empty states, table columns) |
+
+## 5. Common Group Patterns
+
+The second segment (and sometimes third) follows recurring patterns. Use the
+table below as a controlled vocabulary when categorizing strings.
+
+| Group | Used for | Examples |
+|-------|----------|----------|
+| `buttons` | Button labels (`Save`, `Cancel`, `Confirm`, `Apply`) | `shared.buttons.save`, `shared.buttons.cancel` |
+| `labels` | Generic short UI labels not tied to a form input | `shared.labels.required`, `shared.labels.copy` |
+| `messages` | Longer informational messages / confirmations | `shared.messages.confirmDelete`, `shared.messages.unsavedChanges` |
+| `errors` | Error copy (titles, hints) — distinct from validation | `shared.errors.somethingWrong`, `shared.errors.tryAgain` |
+| `forms` | Form field labels & section headings | `addresses.forms.country`, `budgets.forms.startDate` |
+| `validation` | Inline validation / required-field messages | `addresses.validation.cityRequired`, `users.create.emailRequired` |
+| `placeholder` / `placeholders` | Input placeholder text | `budgets.placeholders.currency`, `buyingPolicies.placeholder.criteriaExample` |
+| `tooltip` / `tooltips` | Tooltip / help text | `budgets.tooltip.autoRenew`, `buyingPolicies.tooltip.description` |
+| `aria` | Accessibility labels for non-text controls | `addresses.aria.removeLocationField`, `paymentMethods.aria.selectAll` |
+| `toast` / `toasts` | Toast notifications (success / error / progress) | `users.toast.userAddedSuccess`, `creditCards.toast.defaultError` |
+| `drawer` / `drawers` | Drawer titles, headings and shared drawer copy | `shared.drawer.addTitle`, `creditCards.drawers.deleteCard` |
+| `dropdown` | Dropdown menu items | `users.dropdown.editDetails`, `buyingPolicies.dropdown.open` |
+| `pagination` | Pagination controls | `shared.pagination.counter`, `users.pagination.loadMore` |
+| `navigation` | Top-level navigation labels | `shared.navigation.contract`, `shared.navigation.organization` |
+| `actions` | Verbs / action menu items | `shared.actions.rename`, `shared.actions.setAsDefault` |
+| `links` | Link text | `orgUnitDetails.links.profile` |
+| `titles` | Page / section titles (when not better placed under `forms`/`drawer`) | `shared.titles.switchCustomer` |
+| `countries` | Country names | `addresses.countries.us`, `phone.countries.br` |
+| `currencies` | Currency labels | `budgets.currencies.usd` |
+| `regions` | Locale region labels | `shared.regions.enUS` |
+| `permissions` / `permissionDescriptions` / `roleNames` / `descriptions` | Role-related vocab | `roles.permissions.create` |
+| `create` / `update` / `delete` / `edit` / `reassign` / `reset` / `remove` | Action-flow groupings (form fields, toasts, copy specific to that flow) | `users.create.fullNameLabel`, `users.delete.question` |
+| `criteria` / `workflow` / `details` / `settings` / `settingsInfo` / `notificationsForm` / `notificationsInfo` | Sub-flows of a feature | `buyingPolicies.criteria.spending.unitPriceGtX` |
+| `components` | Container for component-scoped strings (4-segment ids) | `addresses.components.deleteAddress.title` |
+| `table` / `usersTable` / `allocationsTable` | Table column headers and row actions | `budgets.table.columnRemaining`, `budgets.usersTable.columnEmail` |
+| `empty` | Empty-state copy | `budgets.empty.noAllocations`, `layouts.addresses.empty` |
+
+## 6. ICU MessageFormat Placeholders
+
+Strings can include named placeholders enclosed in single braces. They are
+substituted at render time via the `values` prop / argument.
+
+```jsonc
+"users.delete.question": "Permanently delete {userName}?",
+"shared.pagination.counter": "{items} of {total}",
+"buyingPolicies.workflow.levelLabel": "Level {n}",
+"budgets.settingsInfo.periodRange": "{start} to {end}",
+"customFields.settings.intro": "Set how buyers in this unit should enter {fieldPlural} during checkout"
+```
+
+### Conventions for placeholder names
+
+- Use **camelCase** (`userName`, `orgUnitName`, `entityPlural`).
+- Reuse names that already exist for the same concept across the catalog:
+  - `{name}` — generic entity name
+  - `{n}` — ordinal index (e.g. `Level 2`, `Location 3`)
+  - `{count}` — integer count
+  - `{label}`, `{field}`, `{fieldPlural}` — dynamic field/entity label
+  - `{entityName}`, `{entityPlural}` — dynamic entity label
+  - `{userName}`, `{orgUnitName}`, `{addressName}`, `{cardName}`,
+    `{paymentMethodName}`, `{productAssortmentName}`,
+    `{previousOrgUnitName}`, `{existingUserName}` — identifying names
+  - `{email}`, `{emailLink}` — emails
+  - `{items}`, `{shown}`, `{total}` — pagination
+  - `{used}`, `{total}` — amounts (with same name as pagination total)
+  - `{start}`, `{end}` — period ranges
+  - `{max}` — threshold count
+
+> All placeholders that appear in the source string MUST also appear in the
+> translated string in every locale.
+
+## 7. Rich-Text Tags
+
+Strings may include simple XML-like tags for inline rich content. They are NOT
+HTML — they are pseudo-tags resolved by `react-intl` via the `values` prop,
+where the tag name maps to a function that wraps `chunks`.
+
+```jsonc
+"buyingPolicies.form.criteriaIntro": "Define the conditions that will trigger this buying policy using <link>JSONata</link>",
+"budgets.addSuccess.descriptionSecond": "You can edit or remove this policy later in the <link>Buying Policies</link> section."
+```
+
+Rendered with:
+
+```tsx
+<FormattedMessage
+  id="buyingPolicies.form.criteriaIntro"
+  defaultMessage="Define the conditions that will trigger this buying policy using <link>JSONata</link>"
+  values={{
+    link: (chunks) => <a href="https://jsonata.org/" target="_blank" rel="noreferrer">{chunks}</a>,
+  }}
+/>
+```
+
+The only tag in active use is `<link>`. New tags should be:
+
+- All-lowercase, single word (`<bold>`, `<strong>`, `<link>`).
+- Closed properly (`<tag>...</tag>`).
+- Documented in this file when introduced.
+
+## 8. Usage in Code (`react-intl`)
+
+Two equivalent APIs are used. Both rely on the message id existing in every
+locale catalog.
+
+### 8.1 Imperative — `useIntl().formatMessage`
+
+Use when a string is consumed as a plain JavaScript value (props, toast
+messages, `aria-label`, dynamic concatenation):
+
+```tsx
+import { useIntl } from "react-intl";
+
+const intl = useIntl();
+
+pushToast({
+  message: intl.formatMessage({
+    id: "addresses.components.addRecipientsDrawer.toastSuccess",
+    defaultMessage: "Recipients added successfully",
+  }),
+  status: "INFO",
+});
+```
+
+With placeholders:
+
+```tsx
+intl.formatMessage(
+  { id: "users.delete.question", defaultMessage: "Permanently delete {userName}?" },
+  { userName: user.fullName },
+);
+```
+
+### 8.2 Declarative — `<FormattedMessage>`
+
+Use when the string is rendered directly in JSX, especially when it contains
+rich-text tags or React-element placeholders:
+
+```tsx
+import { FormattedMessage } from "react-intl";
+
+<FormattedMessage
+  id="users.create.userAlreadyAssigned.body2"
+  defaultMessage="Users can only belong to one organizational unit at a time. To add {userName} to {orgUnitName}, go to their profile and move them from {previousOrgUnitName}."
+  values={{
+    userName: <strong>{userName}</strong>,
+    orgUnitName: <strong>{orgUnitName}</strong>,
+    previousOrgUnitName: <strong>{previousOrgUnitName}</strong>,
+  }}
+/>
+```
+
+### 8.3 The `defaultMessage` field
+
+- Always provide `defaultMessage` alongside `id`. It MUST be byte-equivalent
+  to the value in the source-of-truth locale (`en-US.json`).
+- Tooling can use `defaultMessage` to detect drift between code and catalogs.
+
+## 9. Authoring & Extraction Workflow
+
+When porting this format to another project, an agent should follow this
+process:
+
+### Step 1 — Identify user-facing strings
+
+Search the codebase for strings that are visible to end users. Common signals:
+
+- JSX text nodes: `<button>Save</button>`
+- Component props that render text: `title="Add user"`, `placeholder="Search"`,
+  `aria-label="Close drawer"`
+- String literals passed to UI helpers: `pushToast({ message: "..." })`,
+  `alert("...")`, `confirm("...")`
+- Validation/error helpers: `setError("...")`, `throw new Error("...")` *(only
+  if surfaced to the user — internal exceptions should NOT be translated)*
+- Constants files used to render UI (e.g. menu definitions)
+
+Do **not** translate:
+
+- Logger / analytics event strings
+- Test fixtures and Cypress selectors
+- Code comments
+- API field names / GraphQL fragment text
+
+### Step 2 — Categorize each string
+
+Pick a `feature` namespace (Section 4) and a `group` (Section 5). Reuse
+existing groups before introducing new ones. Prefer placing reusable, generic
+strings (`Save`, `Cancel`, `Loading...`) under `shared.*`.
+
+### Step 3 — Generate a stable id
+
+Build the id as `<feature>.<group>[.<subGroup>].<name>` with all segments in
+camelCase. Make `name` short, descriptive, and unique within its group. Examples:
+
+| Source string | Where it lives | Suggested id |
+|---------------|----------------|--------------|
+| `Save` (generic) | any button | `shared.buttons.save` |
+| `Add address` | `CreateAddressDrawer` title | `addresses.components.createAddress.title` |
+| `An error occurred while creating the address` | toast | `addresses.components.createAddress.addressCreateError` |
+| `Permanently delete {name}?` | delete drawer | `<feature>.delete.permanentDeleteQuestion` |
+| `Permissions` | role details heading | `roles.permissionsTitle` |
+| `Loading...` | generic spinner | `shared.labels.loading` |
+
+### Step 4 — Replace the literal in code
+
+Pick the API based on usage (Section 8):
+
+```diff
+- <button onClick={onSave}>Save</button>
++ <button onClick={onSave}>
++   <FormattedMessage id="shared.buttons.save" defaultMessage="Save" />
++ </button>
+```
+
+### Step 5 — Update every locale catalog
+
+Add the new id to `src/messages/en-US.json` (source of truth) **and** to every
+other locale file with a localized value. Catalogs MUST stay in sync — missing
+keys in a non-source locale fall back silently and are a bug.
+
+### Step 6 — Validate
+
+- Confirm every `id` used in code exists in every catalog.
+- Confirm placeholder names match between the source string, the
+  `defaultMessage` in code, and every translated value.
+- Confirm rich-text tags (e.g. `<link>...</link>`) are balanced in every locale.
+
+## 10. Skeleton for a New Catalog File
+
+When creating the catalog from scratch in a new project, start with the
+cross-cutting `shared.*` namespace and grow per feature.
+
+```json
+{
+  "shared.buttons.save": "Save",
+  "shared.buttons.cancel": "Cancel",
+  "shared.buttons.delete": "Delete",
+  "shared.buttons.edit": "Edit",
+  "shared.buttons.add": "Add",
+  "shared.buttons.confirm": "Confirm",
+  "shared.buttons.close": "Close",
+  "shared.labels.loading": "Loading...",
+  "shared.labels.required": "Required",
+  "shared.labels.optional": "Optional",
+  "shared.labels.noResults": "No results found",
+  "shared.errors.somethingWrong": "Something went wrong!",
+  "shared.errors.tryAgain": "Try again",
+  "shared.pagination.counter": "{items} of {total}",
+  "shared.drawer.addTitle": "Add {entityName}",
+  "shared.drawer.deleteTitle": "Delete {entityName}",
+  "shared.validation.nameRequired": "Name is required"
+}
+```
+
+Then add feature-specific keys following the same conventions, e.g.:
+
+```json
+{
+  "addresses.forms.country": "Country",
+  "addresses.forms.street": "Street Address",
+  "addresses.validation.streetRequired": "Street Address is required",
+  "addresses.components.deleteAddress.title": "Delete address",
+  "addresses.components.deleteAddress.toastSuccess": "Address deleted successfully"
+}
+```
+
+## 11. Quick Checklist for Agents
+
+Before opening a PR that touches translations:
+
+- [ ] All new ids follow `<feature>.<group>[.<subGroup>].<name>` in camelCase.
+- [ ] Every new id exists in **all** locale files in `src/messages/`.
+- [ ] `defaultMessage` in code matches the value in the source-of-truth locale
+      byte-for-byte (including punctuation and trailing periods).
+- [ ] Placeholder names are camelCase and identical across all locales.
+- [ ] Rich-text tags (`<link>`, etc.) are balanced and reuse existing tags
+      whenever possible.
+- [ ] No nested objects in the catalog — keys are flat dotted strings.
+- [ ] Generic strings landed under `shared.*` rather than duplicated per
+      feature.
+- [ ] No hard-coded user-facing literals remain in the touched components.