intlayer 3.5.11 → 4.0.2

package/README.md

@@ -17,25 +17,78 @@
   </a>
 </div>
 
-# Intlayer: Next-Level Content Management in JavaScript
+# intlayer: NPM Package to Manage Multilingual Content Declaration (i18n)
 
-**Intlayer** is an internationalization library designed specifically for JavaScript developers. It allow the declaration of your content everywhere in your code. It converts declaration of multilingual content into structured dictionaries to integrate easily in your code. Using TypeScript, **Intlayer** make your development stronger and more efficient.
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, Next.js, and Express.js.
+
+**The `intlayer` package** allows you to declare your content anywhere in your code. It converts multilingual content declarations into structured dictionaries that integrate seamlessly into your application. With TypeScript, **Intlayer** enhances your development by providing stronger, more efficient tools.
+
+## Why to integrate Intlayer?
+
+- **JavaScript-Powered Content Management**: Harness the flexibility of JavaScript to define and manage your content efficiently.
+- **Type-Safe Environment**: Leverage TypeScript to ensure all your content definitions are precise and error-free.
+- **Integrated Content Files**: Keep your translations close to their respective components, enhancing maintainability and clarity.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer
+```
+
+### Configure Intlayer
+
+Intlayer provides a configuration file to set up your project. Place this file in the root of your project.
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+> For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
 
 ## Example of usage
 
-```bash
+With Intlayer, you can declare your content in a structured way anywhere in your codebase.
+
+By default, Intlayer scans for files with the extension `.content.{ts,tsx,js,jsx,mjs,cjs}`.
+
+> YYou can modify the default extension by setting the `contentDir` property in the [configuration file](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
+
+```bash codeFormat="typescript"
 .
-├── ClientComponent
-│   ├── index.content.ts
-│   └── index.tsx
-└── ServerComponent
-    ├── index.content.ts
-    └── index.tsx
+├── intlayer.config.ts
+└── src
+    ├── ClientComponent
+    │   ├── index.content.ts
+    │   └── index.tsx
+    └── ServerComponent
+        ├── index.content.ts
+        └── index.tsx
 ```
 
-```tsx
-// ./ClientComponent/index.content.ts
+### Declare your content
+
+Here’s an example of content declaration:
 
+```tsx filePath="src/ClientComponent/index.content.ts" codeFormat="typescript"
 import { type DeclarationContent, t } from "intlayer";
 
 const clientComponentContent = {
@@ -46,195 +99,275 @@ const clientComponentContent = {
       fr: "Bonjour le monde",
       es: "Hola Mundo",
     }),
+    numberOfCar: enu({
+      "<-1": "Less than minus one car",
+      "-1": "Minus one car",
+      "0": "No cars",
+      "1": "One car",
+      ">5": "Some cars",
+      ">19": "Many cars",
+    }),
   },
 } satisfies DeclarationContent;
 
 export default clientComponentContent;
 ```
 
-```tsx
-// ./ClientComponent/index.tsx
-"use client";
+### Build your dictionaries
 
-import { useIntlayer } from "next-intlayer";
+You can build your dictionaries using the [intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/packages/intlayer-cli/readme.md).
 
-export const ClientComponent = () => {
-  const { myTranslatedContent } = useIntlayer("client-component");
+```bash packageManager="npm"
+npx intlayer build
+```
 
-  return <span>{myTranslatedContent}</span>;
-};
+```bash packageManager="yarn"
+yarn intlayer build
 ```
 
-## Why Choose Intlayer?
+```bash packageManager="pnpm"
+pnpm intlayer build
+```
 
-- **JavaScript-Powered Content Management**: Harness the flexibility of JavaScript to define and manage your content efficiently.
-- **Type-Safe Environment**: Leverage TypeScript to ensure all your content definitions are precise and error-free.
-- **Integrated Content Files**: Keep your translations close to their respective components, enhancing maintainability and clarity.
+This command scans all `*.content.*` files, compiles them, and writes the results to the directory specified in your **`intlayer.config.ts`** (by default, `./.intlayer`).
 
-## intlayer package
+A typical output might look like:
 
-`intlayer` package intend to declare your content in a structured way, using JavaScript.
+```bash
+.
+├── .intlayer
+│   ├── dictionary  # Contain the dictionary of your content
+│   │   ├── client-component.json
+│   │   └── server-component.json
+│   ├── main  # Contain the entry point of your dictionary to be used in your application
+│   │   ├── dictionary.cjs
+│   │   └── dictionary.mjs
+│   └── types  # Contain the auto-generated type definitions of your dictionary
+│       ├── client-component.d.ts
+│       └── server-component.d.ts
+└── types
+    └── intlayer.d.ts  # Contain the auto-generated type definitions of Intlayer
+```
 
-To build dictionaries from this declaration, you can use [intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/packages/intlayer-cli/readme.md).
-And to interpret intlayer dictionaries you can interpreters, such as [react-intlayer](https://github.com/aymericzip/intlayer/blob/main/packages/react-intlayer/README.md) [next-intlayer](https://github.com/aymericzip/intlayer/blob/main/packages/next-intlayer/README.md)
+### Build i18next resources
 
-## Getting Started with Intlayer
+Intlayer can be configured to build dictionaries for [i18next](https://www.i18next.com/). For that you need to add the following configuration to your `intlayer.config.ts` file:
 
-[See how to use intlayer with NextJS](https://github.com/aymericzip/intlayer/blob/main/README.md)
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
 
-### Install Package
+const config: IntlayerConfig = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["i18next"],
 
-Install the necessary packages using npm:
+    // The directory where Intlayer will write your message JSON files
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+```
 
-```bash
-npm install intlayer
+```typescript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["i18next"],
+
+    // The directory where Intlayer will write your message JSON files
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+export default config;
 ```
 
-```bash
-yarn add intlayer
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["i18next"],
+
+    // The directory where Intlayer will write your message JSON files
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+module.exports = config;
 ```
 
+> For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
+
+Output:
+
 ```bash
-pnpm add intlayer
+.
+└── i18next
+    └── resources
+        ├── en
+        │   ├── client-component.json
+        │   └── server-component.json
+        ├── es
+        │   ├── client-component.json
+        │   └── server-component.json
+        └── fr
+            ├── client-component.json
+            └── server-component.json
 ```
 
-### Manage Your Content
+For example, the **en/client-component.json** might look like:
 
-Create and manage your content dictionaries:
+```json filePath="intlayer/dictionary/en/client-component.json"
+{
+  "myTranslatedContent": "Hello World",
+  "zero_numberOfCar": "No cars",
+  "one_numberOfCar": "One car",
+  "two_numberOfCar": "Two cars",
+  "other_numberOfCar": "Some cars"
+}
+```
 
-#### Using typescript
+### Build i18next or next-intl dictionaries
 
-```typescript
-// src/app/[locale]/page.content.ts
-import { t, enu, type DeclarationContent } from "intlayer";
+Intlayer can be configured to build dictionaries for [i18next](https://www.i18next.com/) or [next-intl](https://github.com/formatjs/react-intl/tree/main/packages/next-intl). For that you need to add the following configuration to your `intlayer.config.ts` file:
 
-const pageContent = {
-  key: "page",
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  /* ... */
   content: {
-    getStarted: {
-      main: t({
-        en: "Get started by editing",
-        fr: "Commencez par éditer",
-        es: "Comience por editar",
-      }),
-      pageLink: "src/app/page.tsx",
-    },
-    nestedContent: {
-      id: "enumeration",
-      numberOfCar: enu({
-        "<-1": "Less than minus one car",
-        "-1": "Minus one car",
-        "0": "No cars",
-        "1": "One car",
-        ">5": "Some cars",
-        ">19": "Many cars",
-      }),
-    },
-  },
-} satisfies DeclarationContent;
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["next-intl"],
 
-// Content should be exported as default
-export default pageContent;
+    // The directory where Intlayer will write your message JSON files
+    nextIntlMessagesDir: "./i18next/messages",
+  },
+};
 ```
 
-#### Using ECMAScript modules
-
-```javascript
-// src/app/[locale]/page.content.mjs
+```typescript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
 
-import { t } from "intlayer";
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["next-intl"],
 
-/** @type {import('intlayer').DeclarationContent} */
-const pageContent = {
-  "key": "page",
-  getStarted: {
-    main: t({
-      en: "Get started by editing",
-      fr: "Commencez par éditer",
-      es: "Comience por editar",
-    }),
-    pageLink: "src/app/page.tsx",
-  },
-  nestedContent: {
-    id: "enumeration",
-    numberOfCar: enu({
-      "<-1": "Less than minus one car",
-      "-1": "Minus one car",
-      0: "No cars",
-      1: "One car",
-      ">5": "Some cars",
-      ">19": "Many cars",
-    }),
+    // The directory where Intlayer will write your message JSON files
+    nextIntlMessagesDir: "./i18next/messages",
   },
 };
 
-// Content should be exported as default
-export default pageContent;
+export default config;
 ```
 
-#### Using CommonJS modules
-
-```javascript
-// src/app/[locale]/page.content.cjs
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
 
-const { t } = require("intlayer");
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["next-intl"],
 
-/** @type {import('intlayer').DeclarationContent} */
-const pageContent = {
-  "key": "page",
-  getStarted: {
-    main: t({
-      en: "Get started by editing",
-      fr: "Commencez par éditer",
-      es: "Comience por editar",
-    }),
-    pageLink: "src/app/page.tsx",
-  },
-  nestedContent: {
-    id: "enumeration",
-    numberOfCar: enu({
-      "<-1": "Less than minus one car",
-      "-1": "Minus one car",
-      0: "No cars",
-      1: "One car",
-      ">5": "Some cars",
-      ">19": "Many cars",
-    }),
+    // The directory where Intlayer will write your message JSON files
+    nextIntlMessagesDir: "./intl/messages",
   },
 };
 
-// Content should be exported as default
-module.exports = pageContent;
+module.exports = config;
 ```
 
-#### Using JSON
+> For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
+
+Output:
 
-```json5
-// src/app/[locale]/page.content.json
+```bash
+.
+└── intl
+    └── messages
+        ├── en
+        │   ├── client-component.json
+        │   └── server-component.json
+        ├── es
+        │   ├── client-component.json
+        │   └── server-component.json
+        └── fr
+            ├── client-component.json
+            └── server-component.json
+```
+
+For example, the **en/client-component.json** might look like:
+
+```json filePath="intlayer/dictionary/en/client-component.json"
 {
-  "key": "page",
-  getStarted: {
-    main: {
-      nodeType: "translation",
-      en: "Get started by editing",
-      fr: "Commencez par éditer",
-      es: "Comience por editar",
-    },
-    pageLink: "src/app/page.tsx",
-  },
-  nestedContent: {
-    id: "enumeration",
-    nodeType: "enumeration",
-    numberOfCar: {
-      "<-1": "Less than minus one car",
-      "-1": "Minus one car",
-      "0": "No cars",
-      "1": "One car",
-      ">5": "Some cars",
-      ">19": "Many cars",
-    },
-  },
+  "myTranslatedContent": "Hello World",
+  "zero_numberOfCar": "No cars",
+  "one_numberOfCar": "One car",
+  "two_numberOfCar": "Two cars",
+  "other_numberOfCar": "Some cars"
 }
 ```
 
-This version emphasizes ease of use, practical steps, and the professional application of Intlayer in a Next.js environment.
+## CLI tools
+
+Intlayer provides a CLI tool to:
+
+- audit your content declarations and complete missing translations
+- build dictionaries from your content declarations
+- push and pull distant dictionaries from your CMS to your locale project
+
+Consult [intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.md) for more information.
+
+## Use Intlayer into your application
+
+One your content declared, you can consume your Intlayer dictionaries in your application.
+
+Intlayer is available as a package for your application.
+
+### React Application
+
+To use Intlayer in your React application, you can use [react-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/react-intlayer/index.md).
+
+### Next.js Application
+
+To use Intlayer in your Next.js application, you can use [next-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/next-intlayer/index.md).
+
+### Express Application
+
+To use Intlayer in your Express application, you can use [express-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/express-intlayer/index.md).
+
+## Functions provided by `intlayer` package
+
+The `intlayer` package also provides some functions to help you to internationalize your application.
+
+- [`getConfiguration()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getConfiguration.md)
+- [`getTranslationContent()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getTranslationContent.md)
+- [`getEnumerationContent()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getEnumerationContent.md)
+- [`getLocaleName()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getLocaleName.md)
+- [`getLocaleLang()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getLocaleLang.md)
+- [`getHTMLTextDir()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getHTMLTextDir.md)
+- [`getPathWithoutLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getPathWithoutLocale.md)
+- [`getMultilingualUrls()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getMultilingualUrls.md)
+- [`getLocalizedUrl()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getLocalizedUrl.md)
+- [`getPathWithoutLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getPathWithoutLocale.md)
+
+## Read about Intlayer
+
+- [Intlayer Website](https://intlayer.org)
+- [Intlayer Documentation](https://intlayer.org/docs)
+- [Intlayer GitHub](https://github.com/aymericzip/intlayer)
+
+- [Ask your questions to our smart documentation](https://intlayer.org/docs/chat)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intlayer",
-  "version": "3.5.11",
+  "version": "4.0.2",
   "private": false,
   "description": "Manage internationalization in a simple way, through TypeScript, declaration file, declare your multilingual every where in your code.",
   "keywords": [
@@ -58,9 +58,9 @@
     "./package.json"
   ],
   "dependencies": {
-    "@intlayer/cli": "3.5.11",
-    "@intlayer/config": "3.5.11",
-    "@intlayer/core": "^3.5.11"
+    "@intlayer/config": "4.0.2",
+    "@intlayer/core": "^4.0.2",
+    "@intlayer/cli": "4.0.2"
   },
   "devDependencies": {
     "@changesets/changelog-github": "0.5.0",
@@ -74,15 +74,15 @@
     "tsc-alias": "^1.8.10",
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
-    "@utils/eslint-config": "1.0.4",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
+    "@utils/eslint-config": "1.0.4",
     "@utils/tsup-config": "1.0.4"
   },
   "peerDependencies": {
-    "@intlayer/cli": "3.5.11",
-    "@intlayer/config": "3.5.11",
-    "@intlayer/core": "^3.5.11"
+    "@intlayer/cli": "4.0.2",
+    "@intlayer/config": "4.0.2",
+    "@intlayer/core": "^4.0.2"
   },
   "engines": {
     "node": ">=14.18"