intlayer 4.0.0 → 4.0.3

package/README.md

@@ -17,25 +17,78 @@
   </a>
 </div>
 
-# Intlayer: Next-Level Content Management in JavaScript
+# intlayer: 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}`.
+
+> 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,203 @@ 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");
-
-  return <span>{myTranslatedContent}</span>;
-};
+```bash packageManager="npm"
+npx intlayer build
 ```
 
-## Why Choose Intlayer?
+```bash packageManager="yarn"
+yarn 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.
+```bash packageManager="pnpm"
+pnpm intlayer build
+```
 
-## intlayer package
+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 intend to declare your content in a structured way, using JavaScript.
+A typical output might look like:
 
-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)
+```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
+```
 
-## Getting Started with Intlayer
+### Build i18next resources
 
-[See how to use intlayer with NextJS](https://github.com/aymericzip/intlayer/blob/main/README.md)
+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:
 
-### Install Package
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
 
-Install the necessary packages using npm:
+const config: IntlayerConfig = {
+  /* ... */
+  content: {
+    // Tells Intlayer to generate message files for i18next
+    dictionaryOutput: ["i18next"],
 
-```bash
-npm install intlayer
+    // The directory where Intlayer will write your message JSON files
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
 ```
 
-```bash
-yarn add intlayer
-```
+> 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:
+
+```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"
+}
+```
 
-Create and manage your content dictionaries:
+### Build next-intl dictionaries
 
-#### Using typescript
+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:
 
-```typescript
-// src/app/[locale]/page.content.ts
-import { t, enu, type DeclarationContent } from "intlayer";
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
 
-const pageContent = {
-  key: "page",
+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
+> For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md).
 
-```javascript
-// src/app/[locale]/page.content.mjs
+Output:
 
-import { t } from "intlayer";
+```bash
+.
+└── intl
+    └── messages
+        ├── en
+        │   ├── client-component.json
+        │   └── server-component.json
+        ├── es
+        │   ├── client-component.json
+        │   └── server-component.json
+        └── fr
+            ├── client-component.json
+            └── server-component.json
+```
 
-/** @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",
-    }),
-  },
-};
+For example, the **en/client-component.json** might look like:
 
-// Content should be exported as default
-export default pageContent;
+```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 CommonJS modules
+## CLI tools
 
-```javascript
-// src/app/[locale]/page.content.cjs
+Intlayer provides a CLI tool to:
 
-const { t } = require("intlayer");
+- 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
 
-/** @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",
-    }),
-  },
-};
+Consult [intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.md) for more information.
 
-// Content should be exported as default
-module.exports = pageContent;
-```
+## Use Intlayer into your application
 
-#### Using JSON
+One your content declared, you can consume your Intlayer dictionaries in your application.
 
-```json5
-// src/app/[locale]/page.content.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",
-    },
-  },
-}
-```
+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)
 
-This version emphasizes ease of use, practical steps, and the professional application of Intlayer in a Next.js environment.
+- [Ask your questions to our smart documentation](https://intlayer.org/docs/chat)

package/package.json

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