@dialpad/i18n 1.16.0

package/.eslintignore

@@ -0,0 +1 @@
+dist

package/.eslintrc.cjs

@@ -0,0 +1,12 @@
+module.exports = {
+  extends: ['@dialpad'],
+  overrides: [
+    {
+      files: ['*.ts'],
+      parserOptions: {
+        project: ['./eslint-tsconfig.json'],
+        tsconfigRootDir: __dirname,
+      },
+    },
+  ],
+};

package/.prettierignore

@@ -0,0 +1,3 @@
+dist
+CHANGELOG.md
+eslint_report.*

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+## [@dialpad/i18n-v1.16.0](https://github.com/dialpad/web-clients/compare/@dialpad/i18n-v1.15.0...@dialpad/i18n-v1.16.0) (2025-07-02)
+
+
+### Features
+
+* add localstorage wrapper to i18n ([#1321](https://github.com/dialpad/web-clients/issues/1321)) ([1a34a80](https://github.com/dialpad/web-clients/commit/1a34a80c035079decf2670be1bb43a1671aa97eb))
+
+## [@dialpad/i18n-v1.15.0](https://github.com/dialpad/web-clients/compare/@dialpad/i18n-v1.14.1...@dialpad/i18n-v1.15.0) (2025-05-21)
+
+
+### Features
+
+* **infra-7827:** improvements to install in dp1 and to add sources on the fly ([#1273](https://github.com/dialpad/web-clients/issues/1273)) ([8ed826b](https://github.com/dialpad/web-clients/commit/8ed826b8f404b699a4297f25fa5e536bc89bf1c6))
+
+## [@dialpad/i18n-v1.14.1](https://github.com/dialpad/web-clients/compare/@dialpad/i18n-v1.14.0...@dialpad/i18n-v1.14.1) (2025-04-01)
+
+
+### Bug Fixes
+
+* add repository field to package json ([#1241](https://github.com/dialpad/web-clients/issues/1241)) ([6db2cdf](https://github.com/dialpad/web-clients/commit/6db2cdf23ee3e2ee7661a878f122c169bc0ceead))
+
+## [@dialpad/i18n-v1.14.0](https://github.com/dialpad/web-clients/compare/@dialpad/i18n-v1.13.0...@dialpad/i18n-v1.14.0) (2025-03-05)
+
+
+### Features
+
+* **infra-7804:** add translations screenshots flows to upload and check ([#1139](https://github.com/dialpad/web-clients/issues/1139)) ([1aa5a79](https://github.com/dialpad/web-clients/commit/1aa5a790e4485d45ba9d923bb09d6a5186d22621))
+
+## [@dialpad/i18n-v1.13.0](https://github.com/dialpad/web-clients/compare/@dialpad/i18n-v1.12.1...@dialpad/i18n-v1.13.0) (2025-01-23)
+
+
+### Features
+
+* **infra-7599:** add vue2 and vue3 compatibility ([#1126](https://github.com/dialpad/web-clients/issues/1126)) ([f0d016b](https://github.com/dialpad/web-clients/commit/f0d016bfe7bc9f22fd0fc594e303b48487b7cca8))

package/README.md

@@ -0,0 +1,533 @@
+# i18n (Vue 3 compatible)
+
+## Introduction
+
+This package contains all the logic needed to take care the i18n of 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/README.md), based on different
+bundle sources.
+
+## How it works?
+
+There are essentially two main concepts behind the scenes:
+
+### LocaleManager
+
+The LocaleManager extends the BaseLocaleManager to oversee the
+internationalization (i18n) in a Vue3.js application using the
+[Fluent localization framework](https://projectfluent.org/). Its
+responsibilities include:
+
+- **Loading and caching translation bundles:** Manages the `.ftl` data, which
+  maps keys to text for each locale.
+- **Switching the current locale:** Provides methods to change the active
+  language dynamically.
+- **Handling bundle namespaces:** Manages potential duplicate bundle requests
+  from multiple sources, though this feature is still being refined.
+- **Initializing the Vue plugin:** Exposes translation methods (`$t`, `$ta`) to
+  `Vue` templates, enabling localized content within the application.
+
+### BundleSource
+
+The second key concept is the BundleSource interface, which abstracts the
+loading and management of localization resources. This interface has two primary
+implementations: `RawBundleSource` and `HTTPBundleSource`, each designed for
+different use cases.
+
+- `RawBundleSource`: This implementation handles localization resources defined
+  within the application. It organizes these resources defined directly in the
+  application, and imported directly at runtime (for example, using
+  `import(./[locale].ftl`). This approach is ideal for applications with mostly
+  static content.
+
+- `HTTPBundleSource`: This implementation fetches localization resources
+  dynamically from a server. It caches these resources locally, allowing for
+  efficient access while still being flexible enough to load translations on
+  demand.
+
+**Disclaimer:** _Both implementations are provisional and may change as we
+better understand our needs. Currently, `RawBundleSource` is the preferred
+option for most applications._
+
+#### Synchronous Resource Loading with [builtResources](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-services/bundle/bundle-source/raw.js:28:2-34:3)
+
+While the
+[dynamicResources](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-services/bundle/bundle-source/raw.js:2:2-17:3)
+method is used for asynchronously loading resources, the
+[RawBundleSource](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-services/bundle/bundle-source/raw.d.ts:14:0-30:1)
+class also provides a
+[builtResources](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-services/bundle/bundle-source/raw.js:28:2-34:3)
+method for synchronous resource loading. This is useful when you have the
+localization resources available at compile time and prefer to import them
+directly without dealing with promises.
+
+##### How to use [builtResources](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-services/bundle/bundle-source/raw.js:28:2-34:3)
+
+Instead of dynamically importing `.ftl` files, you can import them directly and
+use the
+[builtResources](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-services/bundle/bundle-source/raw.js:28:2-34:3)
+method to process the resources. Here's an example:
+
+```typescript
+import { RawBundleSource } from '@dialpad/i18n-services';
+// Import your .ftl files directly
+import enUSResource from './locales/en-US.ftl';
+import esResource from './locales/es.ftl';
+
+// Create an array of BuiltResource objects
+const builtResourcesArray: BuiltResource[] = [
+  ['en-US', 'namespace', enUSResource],
+  ['es', 'namespace', esResource],
+  // ... add other locales and namespaces as needed
+];
+
+// Convert BuiltResource objects to Resource objects using builtResources
+const resources: Resource[] =
+  RawBundleSource.builtResources(builtResourcesArray);
+
+// Now, resources can be used to instantiate RawBundleSource or for any other purpose
+const bundleSource = new RawBundleSource({ resources });
+```
+
+## Setup
+
+### Installation
+
+```sh
+pnpm add @dialpad/i18n
+```
+
+### Configuration - Static resources
+
+### Integrating LocaleManager with Vue using the [install](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:43:2-55:3) Method
+
+When using `LocaleManager` within a Vue application, **(especially in the
+context of a library, you should be aware that install needs to receive a
+non-default namespace value)** it's important to properly integrate it using the
+[install](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:43:2-55:3)
+method. This method registers `LocaleManager` with the Vue instance, allowing
+for global access to localization functionalities across the application.
+
+#### Usage of [install](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:43:2-55:3)
+
+After creating an instance of `LocaleManager`, you must call the
+[install](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:43:2-55:3)
+method. This method accepts an optional `namespace` parameter, which is
+particularly useful when you are developing a library and need to avoid
+conflicts with other potential instances of `LocaleManager` in the consumer's
+environment.
+
+By using different namespaces, you can have multiple instances of
+`LocaleManager` available globally in Vue. This is ideal for libraries that may
+be used in conjunction with other Vue plugins or in larger applications where
+scoped localization management is required.
+
+##### Parameters
+
+- `namespace`: (Optional) The namespace under which the `LocaleManager` will be
+  registered. Defaults to `'default'` if no namespace is provided.
+
+##### Example
+
+```typescript
+import Vue from 'vue';
+import { LocaleManager } from '@dialpad/i18n-vue2';
+
+// Create a LocaleManager instance with your configuration options
+const localeManager = new LocaleManager({
+  // ... configuration options, see on Dynamic resources configuration section
+});
+
+// Install the LocaleManager with a specific namespace to avoid conflicts
+localeManager.install('my-namespace');
+
+// Your library's users can now access the LocaleManager instance globally in Vue
+new Vue({
+  // ... other options
+}).$mount('#app');
+```
+
+### Configuration - Dynamic resources
+
+We recommend you to include this in your own composable that handle every locale
+and i18n set up logic, i.e.:
+
+```ts
+//src/localization/i18n.ts
+import type { App } from 'vue';
+import { LocaleManager, RawBundleSource } from '@dialpad/i18n';
+
+export async function hostI18NManager({
+  vueApp,
+}: {
+  vueApp: App;
+}): Promise<void> {
+  const bundleSource = new RawBundleSource({
+    resources: await RawBundleSource.dynamicResources([
+      ['en-US', 'your-app', import('./en-US.ftl?raw')],
+    ]),
+  });
+
+  const manager = new LocaleManager({
+    bundleSource,
+    preferredLocale: 'en-US', // optional
+    allowedLocales: ['en-US'], // optional
+    fallbackLocale: 'en-US',
+    namespaces: ['your-app'],
+  });
+
+  await manager.ready;
+
+  vueApp.use(manager);
+}
+```
+
+**Important note:** let's say that you have more than one `allowedLocales`, or
+that your `fallbackLocale`/`preferredLocale` is different from what you're
+specifying on the `allowedLocales` prop to the `LocaleManager` instance. In
+those cases you need to verify that you have specified a Bundle resource for
+each locale, in order to have them working properly, i.e.:
+
+```ts
+//src/localization/i18n.ts
+import type { App } from 'vue';
+import { LocaleManager, RawBundleSource } from '@dialpad/i18n';
+
+export async function hostI18NManager({
+  vueApp,
+}: {
+  vueApp: App;
+}): Promise<void> {
+  const bundleSource = new RawBundleSource({
+    resources: await RawBundleSource.dynamicResources([
+      // You must **always** have one resource per locale.
+      ['dp-DP', 'your-app', import('./dp-DP.ftl?raw')],
+      // This one is for the `fallbackLocale`
+      ['en-US', 'your-app', import('./en-US.ftl?raw')],
+    ]),
+  });
+
+  const manager = new LocaleManager({
+    bundleSource,
+    // I'm using Dialpadistan as my locale
+    preferredLocale: 'dp-DP',
+    // But my fallback is en-US (if it was part of the locales this is the same concept, **you need to add one resource per locale**)
+    fallbackLocale: 'en-US',
+    namespaces: ['your-app'],
+  });
+
+  await manager.ready;
+
+  vueApp.use(manager);
+}
+```
+
+After this, you should plug this into your `main.ts`. You will call it like:
+
+```ts
+// src/main.ts
+
+import { createHost } from '@dialpad/host-entry';
+import { hostI18NManager } from './localization/i18n';
+import { hostEnv } from './constants';
+
+await createHost(hostEnv)
+  // ... all your config
+  .vueCreated(hostI18NManager)
+  // ... some other config
+  .start();
+```
+
+## Usage
+
+### User's locale selection criteria
+
+You will find that this API is (and should always be) the same as the
+[i18n-vue2 tool](../i18n-vue2/README.md).
+
+When instantiating the LocaleManager (or when calling setI18N), the
+preferredLocale and allowedLocales parameters are optional. BUT this is the
+following criteria to select it.
+
+If preferredLocale param is provided, use that. If allowedLocales param is
+provided, use the first one. If localStorage contains the previously-used value,
+use that. If navigator.language is available, use that. Use the fallbackLocale.
+
+First of all you need to understand he difference between `$t` and `$ta`, which
+mainly lies in their outputs:
+
+### useI18N() hook API
+
+There are three main functions exported: `$t`, `$ta`, and `setI18N()`, and two
+exported values: `currentLocale` and `allowedLocales`.
+
+(Keep in mind that you should have a fluent file (en-US.ftl in this case)
+following the Fluent rules.)
+
+#### `$t`
+
+Returns a translated string based on a key and optional variables. It’s used for
+simple text translations.
+
+```ftl
+# src/localization/en-US.ftl
+PARAGRAPH_KEY = Amazing paragraph, { $name }
+```
+
+```ts
+// Component file
+const greeting = $t('PARAGRAPH_KEY', { name: 'John' });
+// Output: "Amazing paragraph, John"
+```
+
+#### `$ta`
+
+Returns an object containing translated attributes to pass directly as props to
+components, it can contain aria-label, title, etc, rather than just a plain
+text. It’s useful for handling element attributes in the UI.
+
+```ftl
+# src/localization/en-US.ftl
+BUTTON_NAME =
+  .aria-label = { $title } now
+  .title = { $title }
+```
+
+```ts
+// Component file
+const buttonAttrs = $ta('BUTTON_NAME', { title: 'Submit' });
+
+// Output: { ariaLabel: "Submit now", title: "Submit" }
+
+// Usage:
+<template>
+  <DtButton v-bind="$ta('BUTTON_NAME', { title: 'Submit' });" />
+</template>;
+```
+
+In both cases, any valid fluent syntax is allowed, so the usage of
+[it might include functions](https://projectfluent.org/fluent/guide/functions.html)
+or any other feature provided [by the framework](https://projectfluent.org/).
+(You can find
+[real world examples on this file](../app-core/src/localization/en-US.ftl))
+
+##### Vue component example - $t, $ta
+
+Here's an example of how to use the `LocaleManager` in a `Vue` component.
+
+```vue
+<script>
+/* `useI18N` exposes the `$t` and `$ta` localization methods, **for use in the setup method**, and these are both available by default in templates with no extra calls needed. */
+
+import { useI18N } from '@dialpad/i18n';
+
+const { $t, $ta } = useI18N();
+</script>
+
+<template>
+  <div>
+    <p>{{ $t('PARAGRAPH_KEY') }}</p>
+    <button
+      v-bind="
+        $ta('BUTTON_NAME', {
+          name,
+        })
+      "
+    />
+  </div>
+</template>
+```
+
+using the following Fluent file as example:
+
+```ftl
+# src/localization/en-US.ftl
+PARAGRAPH_KEY = Amazing paragraph, { $name }
+BUTTON_NAME =
+  .aria-label = { $title } now
+  .title = { $title }
+```
+
+#### `setI18N`
+
+This function receives a `Partial<SetLocaleParams>`. This allows you to change
+any of the set up parameters after the initialization of the `LocaleManager`,
+but the main use case is to change locales dynamically.
+
+You probably want to use this in addition to:
+
+- `currentLocale`, determined by the
+  [criteria defined in the usage section](#usage).
+- `allowedLocales`, are all the allowed locale codes, sorted alphabetically,
+  defined during initialization of the `LocaleManager`.
+
+##### Vue component example - setI18N, allowedLocales, currentLocales
+
+```vue
+<script setup lang="ts">
+// your imports ...
+const { setI18N, allowedLocales, currentLocale } = useI18N();
+</script>
+
+<template>
+  <DtDropdown placement="bottom-end">
+    <template #anchor="{ attrs }">
+      <DtButton v-bind="attrs" size="md" importance="clear">
+        {{ currentLocale }}
+      </DtButton>
+    </template>
+    <template #list="{ close }">
+      <template v-for="locale in allowedLocales" :key="locale">
+        <DtListItem
+          navigation-type="tab"
+          @click="
+            setI18N({ locales: locale });
+            close();
+          "
+        >
+          {{ locale }}
+        </DtListItem>
+      </template>
+    </template>
+  </DtDropdown>
+</template>
+```
+
+### Dynamically Changing Locales with [changeLocale](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:64:2-88:3) Method
+
+The
+[changeLocale](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:64:2-88:3)
+method provides the functionality to dynamically change the current locale of
+your application. This method can target a specific
+[LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)
+by namespace or all
+[LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)
+instances globally.
+
+#### changeLocale()
+
+To change the locale settings, call the
+[changeLocale](cci:1://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:64:2-88:3)
+method on your
+[LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)
+instance. You can pass optional parameters to update the locale settings and
+optionally specify a namespace to target a specific
+[LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1).
+If no namespace is provided, the locale settings will be updated for all
+[LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)
+instances.
+
+##### Parameters
+
+- `args`: (Optional) A `Partial<SetLocaleParams>` object containing the new
+  locale settings to be applied.
+- `namespace`: (Optional) The namespace of the
+  [LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)
+  instance whose locale settings you want to change. If not provided, all
+  instances will be updated.
+
+###### Behavior
+
+- Retrieves the map of
+  [LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)
+  instances from the Vue prototype.
+- If a namespace is specified, it targets the corresponding
+  [LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)
+  and throws an error if it does not exist.
+- If no namespace is specified, it targets all registered
+  [LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)
+  instances.
+- Updates the locale settings for the targeted
+  [LocaleManager](cci:2://file:///Users/daniellovero/src/web-clients/packages/i18n-vue2/src/locale-manager.ts:21:0-89:1)(s)
+  using the provided arguments.
+
+###### Example
+
+```typescript
+// Assuming you have a LocaleManager instance
+const manager = new LocaleManager(...);
+
+// To change the locale settings for a specific namespace
+manager.changeLocale({ preferredLocale: 'fr-FR' }, 'myNamespace');
+
+// To change the locale settings for all LocaleManager instances
+manager.changeLocale({ preferredLocale: 'fr-FR' });
+
+### Adding Resources at Runtime with `addSources`
+
+#### API Method: `addSources`
+
+The `addSources` method allows you to add multiple translation resources to the `LocaleManager` at runtime. Once all resources are loaded, it triggers the `ready` promise indicating that the locale manager is fully initialized and ready to handle localization requests.
+```
+
+### Adding Resources at Runtime with `addSources`
+
+#### API Method: `addSources`
+
+The `addSources` method allows you to add multiple translation resources to the
+`LocaleManager` at runtime. Once all resources are loaded, it triggers the
+`ready` promise indicating that the locale manager is fully initialized and
+ready to handle localization requests.
+
+##### Parameters
+
+- `sources`: An array of `BuiltResource` items where each item contains:
+  - `locale`: The locale code for the translation resource.
+  - `namespace`: The namespace associated with the resource.
+  - `source`: The actual source string or a promise that resolves to the source
+    string.
+
+##### Example
+
+```typescript
+// Assuming you have a LocaleManager instance
+const manager = new LocaleManager(...);
+
+// Define your resources
+const resourcesToAdd: BuiltResource[] = [
+  // Array of [locale, namespace, source] tuples
+  ['en-US', 'namespace1', sourceStringOrPromise],
+  ['es-ES', 'namespace1', anotherSourceStringOrPromise],
+  // Add more resources as needed
+];
+
+// Add the resources to the LocaleManager
+manager.addSources(resourcesToAdd);
+```
+
+## Context screenshots
+
+Context screenshots are, as their name suggest, screenshots that provide context
+to recognize where each translation is used in each app.
+
+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.
+
+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.
+
+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
+should have a sibling screenshots directory. Each screenshot has a file size
+limit of 20MB.
+
+The screenshots are uploaded to smartling along with the CSV/FTL files through a
+github action when a PR to main is merged.
+
+## Resources
+
+- [Fluent docs](https://github.com/projectfluent/fluent/wiki)
+- [I18n best practices](https://localization.blog/2022/05/16/i18n-best-practices-keep-it-together/)
+- [18n-services docs](../i18n-services/README.md)
+- [i18n for vue2 docs](../i18n-vue2/README.md)

package/base-tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": false,
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "experimentalDecorators": true,
+    "resolveJsonModule": true,
+    "jsx": "preserve",
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "types": ["vite/client", "vitest/globals"],
+    "noPropertyAccessFromIndexSignature": false,
+    "verbatimModuleSyntax": true
+  }
+}