@vocab/phrase 2.0.2 → 2.1.1

package/README.md

@@ -13,6 +13,17 @@ Vocab helps you ship multiple languages without compromising the reliability of
 - **Strongly typed with TypeScript**\
   When using translations TypeScript will ensure code only accesses valid translations and translations are passed all required dynamic values.
 
+## Table of contents
+
+- [Getting started](#getting-started)
+  - [Step 1: Install Dependencies](#step-1-install-dependencies)
+  - [Step 2: Configure Vocab](#step-2-configure-vocab)
+  - [Step 3: Set the language using the React Provider](#step-3-set-the-language-using-the-react-provider)
+  - [Step 4: Create translations](#step-4-create-translations)
+  - [Step 5: Compile and consume translations](#step-5-compile-and-consume-translations)
+  - [Step 6: [Optional] Set up plugin](#step-6-optional-set-up-plugin)
+  - [Step 7: [Optional] Optimize for fast page loading](#step-7-optional-optimize-for-fast-page-loading)
+
 ## Getting started
 
 ### Step 1: Install Dependencies
@@ -159,7 +170,9 @@ function MyComponent({ children }) {
 }
 ```
 
-### Step 6: [Optional] Set up Webpack plugin
+### Step 6: [Optional] Set up plugin
+
+#### Webpack Plugin
 
 With the default setup, every language is loaded into your web application all the time, potentially leading to a large bundle size.
 Ideally you will want to switch out the Node.js/default runtime for the web runtime, which only loads the active language.
@@ -181,6 +194,85 @@ module.exports = {
 };
 ```
 
+#### Vite Plugin _(this plugin is experimental)_
+
+> [!NOTE]
+> This plugin is still experimental and may not work in all cases. If you encounter any issues, please open an issue on the Vocab GitHub repository.
+
+Vocab also provides a Vite plugin to handle the same functionality as the Webpack plugin.
+
+```shell
+npm i --save-dev @vocab/vite
+```
+
+default usage
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import { vocabPluginVite } from '@vocab/vite';
+import vocabConfig from './vocab.config.cjs';
+
+export default defineConfig({
+  plugins: [
+    vocabPluginVite({
+      vocabConfig
+    })
+  ]
+});
+```
+
+#### createVocabChunks
+
+If you want to combine all language files into a single chunk, you can use the `createVocabChunks` function.
+Simply use the function in your `manualChunks` configuration.
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import { vocabPluginVite } from '@vocab/vite';
+import { createVocabChunks } from '@vocab/vite/create-vocab-chunks';
+import vocabConfig from './vocab.config.cjs';
+
+export default defineConfig({
+  plugins: [
+    vocabPluginVite({
+      vocabConfig
+    })
+  ],
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: (id, ctx) => {
+          // handle your own manual chunks before or after the vocab chunks.
+          const languageChunkName = createVocabChunks(
+            id,
+            ctx
+          );
+          if (languageChunkName) {
+            // vocab has found a language chunk. Either return it or handle it in your own way.
+            return languageChunkName;
+          }
+        }
+      }
+    }
+  }
+});
+```
+
+#### VocabPluginOptions
+
+```ts
+type VocabPluginOptions = {
+  /**
+   * The Vocab configuration file.
+   * The type can be found in the `@vocab/core/types`.
+   * This value is required
+   */
+  vocabConfig: UserConfig;
+};
+```
+
 ### Step 7: [Optional] Optimize for fast page loading
 
 Using the above method without optimizing what chunks webpack uses you may find the page needing to do an extra round trip to load languages on a page.
@@ -207,7 +299,7 @@ extractor.addChunk(chunkName);
 
 Translation messages can sometimes contain dynamic values, such as dates/times, links, usernames, etc.
 These values often exist somewhere in the middle of a message, and could change location depending on the translation.
-To support this, Vocab uses [Format.js's `intl-messageformat` library], which enables you to use [ICU Message syntax](https://formatjs.io/docs/core-concepts/icu-syntax/) in your messages.
+To support this, Vocab uses [Format.js's `intl-messageformat` library], which enables you to use [ICU Message syntax](https://formatjs.github.io/docs/core-concepts/icu-syntax/) in your messages.
 
 In the below example we are defining two messages: one that accepts a single parameter, and one that accepts a component.
 
@@ -231,7 +323,7 @@ t('my key with component', {
 });
 ```
 
-[Format.js's `intl-messageformat` library]: https://formatjs.io/docs/intl-messageformat/
+[Format.js's `intl-messageformat` library]: https://formatjs.github.io/docs/intl-messageformat/
 
 ## Overriding the Locale
 
@@ -254,7 +346,7 @@ This can be useful in certain situations:
   For example: `th-u-ca-gregory`.
   See the [MDN Intl docs] for more information on BCP 47 extension sequences.
 
-[`intl-messageformat`]: https://formatjs.io/docs/intl-messageformat/
+[`intl-messageformat`]: https://formatjs.github.io/docs/intl-messageformat/
 [IETF language tag]: https://en.wikipedia.org/wiki/IETF_language_tag
 [mdn intl docs]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument
 
@@ -311,8 +403,8 @@ const Currency = ({ value, currency }) => {
 };
 ```
 
-[numbers]: https://formatjs.io/docs/core-concepts/icu-syntax/#number-type
-[dates, and times]: https://formatjs.io/docs/core-concepts/icu-syntax/#supported-datetime-skeleton
+[numbers]: https://formatjs.github.io/docs/core-concepts/icu-syntax/#number-type
+[dates, and times]: https://formatjs.github.io/docs/core-concepts/icu-syntax/#supported-datetime-skeleton
 
 ## Configuration
 
@@ -452,7 +544,7 @@ const App = () => (
 );
 ```
 
-[icu message syntax]: https://formatjs.io/docs/intl-messageformat/#message-syntax
+[icu message syntax]: https://formatjs.github.io/docs/intl-messageformat/#message-syntax
 [diacritics]: https://en.wikipedia.org/wiki/Diacritic
 
 ## Pseudo-localization
@@ -629,6 +721,17 @@ referenced in the upload. These keys can be deleted from Phrase by providing the
 vocab push --branch my-branch --delete-unused-keys
 ```
 
+#### Ignoring Files
+
+The `ignore` key in your [Vocab config](#configuration) allows you to ignore certain files from being validated, compiled and uploaded.
+However, in some cases you may only want certain files to be compiled and validated, but not uploaded, such as those present in a build output directory.
+This can be accomplished by providing the `--ignore` flag to `vocab push`.
+This flag accepts an array of glob patterns to ignore.
+
+```sh
+vocab push --branch my-branch --ignore "**/dist/**" "**/another_ignored_directory/**"
+```
+
 [phrase]: https://developers.phrase.com/api/
 
 #### [Tags]

package/dist/declarations/src/push-translations.d.ts

@@ -2,10 +2,11 @@ import { type UserConfig } from '@vocab/core';
 interface PushOptions {
     branch: string;
     deleteUnusedKeys?: boolean;
+    ignore?: string[];
 }
 /**
  * Uploads translations to the Phrase API for each language.
  * A unique namespace is appended to each key using the file path the key came from.
  */
-export declare function push({ branch, deleteUnusedKeys }: PushOptions, config: UserConfig): Promise<void>;
+export declare function push({ branch, deleteUnusedKeys, ignore }: PushOptions, config: UserConfig): Promise<void>;
 export {};

package/dist/vocab-phrase.cjs.d.ts

@@ -1,2 +1,2 @@
-export * from "./declarations/src/index";
+export * from "./declarations/src/index.js";
 //# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidm9jYWItcGhyYXNlLmNqcy5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi9kZWNsYXJhdGlvbnMvc3JjL2luZGV4LmQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEifQ==

package/dist/vocab-phrase.cjs.dev.js

@@ -296,13 +296,20 @@ async function pull({
  */
 async function push({
   branch,
-  deleteUnusedKeys: deleteUnusedKeys$1
+  deleteUnusedKeys: deleteUnusedKeys$1,
+  ignore
 }, config) {
+  if (ignore) {
+    trace(`ignoring files on paths: ${ignore.join(', ')}`);
+  }
   const allLanguageTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
     includeNodeModules: false,
     withTags: true
-  }, config);
+  }, {
+    ...config,
+    ignore: [...(config.ignore || []), ...(ignore || [])]
+  });
   trace(`Pushing translations to branch ${branch}`);
   const allLanguages = config.languages.map(v => v.name);
   await ensureBranch(branch);

package/dist/vocab-phrase.cjs.prod.js

@@ -296,13 +296,20 @@ async function pull({
  */
 async function push({
   branch,
-  deleteUnusedKeys: deleteUnusedKeys$1
+  deleteUnusedKeys: deleteUnusedKeys$1,
+  ignore
 }, config) {
+  if (ignore) {
+    trace(`ignoring files on paths: ${ignore.join(', ')}`);
+  }
   const allLanguageTranslations = await core.loadAllTranslations({
     fallbacks: 'none',
     includeNodeModules: false,
     withTags: true
-  }, config);
+  }, {
+    ...config,
+    ignore: [...(config.ignore || []), ...(ignore || [])]
+  });
   trace(`Pushing translations to branch ${branch}`);
   const allLanguages = config.languages.map(v => v.name);
   await ensureBranch(branch);

package/dist/vocab-phrase.esm.js

@@ -286,13 +286,20 @@ async function pull({
  */
 async function push({
   branch,
-  deleteUnusedKeys: deleteUnusedKeys$1
+  deleteUnusedKeys: deleteUnusedKeys$1,
+  ignore
 }, config) {
+  if (ignore) {
+    trace(`ignoring files on paths: ${ignore.join(', ')}`);
+  }
   const allLanguageTranslations = await loadAllTranslations({
     fallbacks: 'none',
     includeNodeModules: false,
     withTags: true
-  }, config);
+  }, {
+    ...config,
+    ignore: [...(config.ignore || []), ...(ignore || [])]
+  });
   trace(`Pushing translations to branch ${branch}`);
   const allLanguages = config.languages.map(v => v.name);
   await ensureBranch(branch);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocab/phrase",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/seek-oss/vocab.git",
@@ -17,7 +17,7 @@
     "csv-stringify": "^6.2.3",
     "debug": "^4.3.1",
     "picocolors": "^1.0.0",
-    "@vocab/core": "^1.6.3"
+    "@vocab/core": "^1.6.4"
   },
   "devDependencies": {
     "@types/debug": "^4.1.5",