@intlayer/docs 5.8.1 → 6.0.0-canary.1

package/docs/en/intlayer_CMS.md

@@ -262,7 +262,7 @@ The Intlayer CMS is able to hot reload the dictionaries when a change is detecte
 
 Without the hot reloading, a new build of the application will be needed to display the new content.
 
-By activating the [`hotReload`](https://intlayer.org/doc/concept/configuration#editor-configuration) configuration, the application will automatically replace the updated content when it is detected.
+By activating the [`liveSync`](https://intlayer.org/doc/concept/configuration#editor-configuration) configuration, the application will automatically replace the updated content when it is detected.
 
 ```typescript fileName="intlayer.config.ts" codeFormat="typescript"
 import type { IntlayerConfig } from "intlayer";
@@ -280,7 +280,7 @@ const config: IntlayerConfig = {
      *
      * Default: false
      */
-    hotReload: true,
+    liveSync: true,
   },
 };
 
@@ -302,7 +302,7 @@ const config = {
      *
      * Default: false
      */
-    hotReload: true,
+    liveSync: true,
   },
 };
 
@@ -324,7 +324,7 @@ const config = {
      *
      * Default: false
      */
-    hotReload: true,
+    liveSync: true,
   },
 };
 
@@ -355,6 +355,7 @@ If you encounter any issues with the CMS, check the following:
 
 ## Doc History
 
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |
+| Version | Date       | Changes                                 |
+| ------- | ---------- | --------------------------------------- |
+| 6.0.0   | 2025-09-04 | Replace `hotReload` field by `liveSync` |
+| 5.5.10  | 2025-06-29 | Init history                            |

package/docs/en/intlayer_cli.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-07-11
+updatedAt: 2025-09-17
 title: CLI
 description: Discover how to use the Intlayer CLI to manage your multilingual website. Follow the steps in this online documentation to set up your project in a few minutes.
 keywords:
@@ -83,6 +83,20 @@ This command will find your declaration content files as default as `./src/**/*.
 - `npx intlayer dictionary build`
 - `npx intlayer dic build`
 
+##### Arguments:
+
+- **`--base-dir`**: Specify the base directory for the project. To retrieve the intlayer configuration, the command will look for the `intlayer.config.{ts,js,json,cjs,mjs}` file in the base directory.
+
+  > Example: `npx intlayer build --base-dir ./src`
+
+- **`--env`**: Specify the environment (e.g., `development`, `production`). Useful in the case you use environment variables in your intlayer configuration file.
+
+  > Example: `npx intlayer build --env production`
+
+- **`--env-file`**: Provide a custom environment file to load variables from. Useful in the case you use environment variables in your intlayer configuration file.
+
+  > Example: `npx intlayer build --env-file .env.production.local`
+
 ### Push dictionaries
 
 ```bash
@@ -243,7 +257,7 @@ This command analyzes your content declaration files for potential issues such a
 
 - **`--output-locales [outputLocales...]`**: Target locales to translate to. If not specified, all locales from your configuration will be used except the source locale.
 
-- **`--mode [mode]`**: Translation mode: 'complete', 'review', or 'missing-only'. Default is 'missing-only'.
+- **`--mode [mode]`**: Translation mode: `complete`, `review`. Default is `complete`. `complete` will fill all missing content, `review` will fill missing content and review existing keys.
 
 **Git options:**
 
@@ -296,6 +310,93 @@ npx intlayer fill --file src/home/*.content.ts --source-locale en --output-local
 
 This command will translate content from English to French and Spanish for all content declaration files in the `src/home/` directory using the GPT-3.5 Turbo model.
 
+### Test missing translations
+
+```bash
+npx intlayer content test
+```
+
+This command analyzes your content declaration files to identify missing translations across all configured locales. It provides a comprehensive report showing which translation keys are missing for which locales, helping you maintain consistency across your multilingual content.
+
+##### Example output:
+
+```bash
+pnpm intlayer content test
+Missing translations:
+ - home-page                      - tr         - src/components/HomePage/homePage.content.ts
+ - server-component               - es, tr     - src/components/ServerComponent/serverComponent.content.ts
+ - client-component               - pl, tr     - src/components/ClientComponent/clientComponent.content.ts
+Locales: en, ru, ja, fr, ko, zh, es, de, ar, it, en-GB, pt, hi, tr, pl
+Required locales: en
+Missing locales: pl, tr, es
+Missing required locales: -
+Total missing locales: 3
+Total missing required locales: 0
+```
+
+##### Arguments:
+
+**Configuration options:**
+
+- **`--env`**: Specify the environment (e.g., `development`, `production`).
+- **`--env-file [envFile]`**: Provide a custom environment file to load variables from.
+- **`--base-dir`**: Specify the base directory for the project.
+
+  > Example: `npx intlayer content test --base-dir ./src --env-file .env.production.local`
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging.
+
+  > Example: `npx intlayer content test --verbose`
+
+##### Example:
+
+```bash
+npx intlayer content test --verbose
+```
+
+##### Example output:
+
+```bash
+npx intlayer content list
+Content declaration files:
+ - home-page        - src/components/HomePage/homePage.content.ts
+ - server-component - src/components/ServerComponent/serverComponent.content.ts
+ - client-component - src/components/ClientComponent/clientComponent.content.ts
+
+Total content declaration files: 3
+```
+
+This command will scan all your content declaration files and display:
+
+- A detailed list of missing translations with their keys, missing locales, and file paths
+- Summary statistics including total missing locales and missing required locales
+- Color-coded output for easy identification of issues
+
+The output helps you quickly identify which translations need to be completed to ensure your application works properly across all configured locales.
+
+### List content declaration files
+
+```bash
+npx intlayer content list
+```
+
+This command displays all content declaration files in your project, showing their dictionary keys and file paths. It's useful for getting an overview of all your content files and verifying that they are properly discovered by Intlayer.
+
+##### Example:
+
+```bash
+npx intlayer content list
+```
+
+This command will output:
+
+- A formatted list of all content declaration files with their keys and relative file paths
+- The total count of content declaration files found
+
+The output helps you verify that all your content files are properly configured and discoverable by the Intlayer system.
+
 ### Manage Configuration
 
 #### Get Configuration
@@ -365,7 +466,6 @@ npx intlayer doc translate
   > Example: `npx intlayer doc translate --excluded-glob-pattern "docs/internal/**"`
 
 - **`--skip-if-modified-before [skipIfModifiedBefore]`**: Skip the file if it has been modified before the given time.
-
   - Can be an absolute time as "2025-12-05" (string or Date)
   - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
   - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file.
@@ -373,7 +473,6 @@ npx intlayer doc translate
   > Example: `npx intlayer doc translate --skip-if-modified-before "2025-12-05"`
 
 - **`--skip-if-modified-after [skipIfModifiedAfter]`**: Skip the file if it has been modified within the given time.
-
   - Can be an absolute time as "2025-12-05" (string or Date)
   - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
   - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file.
@@ -424,7 +523,6 @@ npx intlayer doc translate
 **Custom instructions options:**
 
 - **`--custom-instructions [customInstructions]`**: Custom instructions added to the prompt. Usefull to apply specific rules regarding formatting, urls translation, etc.
-
   - Can be an absolute time as "2025-12-05" (string or Date)
   - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
   - This option check update time of the file using the `fs.stat` method. So it could be impacted by Git or other tools that modify the file.
@@ -488,6 +586,8 @@ If you activated one of the git options, the command will only review the part o
   "intlayer:push": "npx intlayer push",
   "intlayer:pull": "npx intlayer pull",
   "intlayer:fill": "npx intlayer fill",
+  "intlayer:list": "npx intlayer content list",
+  "intlayer:test": "npx intlayer content test",
   "intlayer:doc:translate": "npx intlayer doc translate",
   "intlayer:doc:review": "npx intlayer doc review"
 }
@@ -517,6 +617,8 @@ import {
   pull,
   fill,
   build,
+  listContentDeclaration,
+  testMissingTranslations,
   docTranslate,
   docReview,
 } from "@intlayer/cli";
@@ -529,6 +631,10 @@ fill();
 // ...
 build();
 // ...
+listContentDeclaration();
+// ...
+testMissingTranslations();
+// ...
 docTranslate();
 // ...
 docReview();
@@ -569,5 +675,6 @@ npx clear-npx-cache
 
 | Version | Date       | Changes                                     |
 | ------- | ---------- | ------------------------------------------- |
+| 6.0.0   | 2025-09-17 | Add content test and list command           |
 | 5.5.11  | 2025-07-11 | Update CLI command parameters documentation |
 | 5.5.10  | 2025-06-29 | Init history                                |

package/docs/en/intlayer_with_nestjs.md

@@ -0,0 +1,268 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Translate your Nest backend (i18n)
+description: Discover how to make your vite backend multilingual. Follow the documentation to internationalize (i18n) and translate it.
+keywords:
+  - Internationalization
+  - Documentation
+  - Intlayer
+  - NestJS
+  - JavaScript
+  - Backend
+slugs:
+  - doc
+  - environment
+  - nest
+applicationTemplate: https://github.com/AydinTheFirst/nestjs-intlayer
+author: AydinTheFirst
+---
+
+# Getting Started internationalizing (i18n) with Intlayer and NestJS
+
+`express-intlayer` is a powerful internationalization (i18n) middleware for Express applications, designed to make your backend services globally accessible by providing localized responses based on the client's preferences. Since NestJS is built on top of Express, you can seamlessly integrate `express-intlayer` into your NestJS applications to handle multilingual content effectively.
+
+## Why Internationalize Your Backend?
+
+Internationalizing your backend is essential for serving a global audience effectively. It allows your application to deliver content and messages in the preferred language of each user. This capability enhances user experience and broadens your application's reach by making it more accessible and relevant to people from different linguistic backgrounds.
+
+### Practical Use Cases
+
+- **Displaying Backend Errors in User's Language**: When an error occurs, displaying messages in the user's native language improves understanding and reduces frustration. This is especially useful for dynamic error messages that might be shown in front-end components like toasts or modals.
+
+- **Retrieving Multilingual Content**: For applications pulling content from a database, internationalization ensures that you can serve this content in multiple languages. This is crucial for platforms like e-commerce sites or content management systems that need to display product descriptions, articles, and other content in the language preferred by the user.
+
+- **Sending Multilingual Emails**: Whether it's transactional emails, marketing campaigns, or notifications, sending emails in the recipient’s language can significantly increase engagement and effectiveness.
+
+- **Multilingual Push Notifications**: For mobile applications, sending push notifications in a user's preferred language can enhance interaction and retention. This personal touch can make notifications feel more relevant and actionable.
+
+- **Other Communications**: Any form of communication from the backend, such as SMS messages, system alerts, or user interface updates, benefits from being in the user's language, ensuring clarity and enhancing the overall user experience.
+
+By internationalizing the backend, your application not only respects cultural differences but also aligns better with global market needs, making it a key step in scaling your services worldwide.
+
+## Getting Started
+
+### Create a new NestJS Project
+
+```bash packageManager="npm"
+npm install -g @nestjs/cli
+nest new my-nest-app
+```
+
+### Installation
+
+To begin using `express-intlayer`, install the package using npm:
+
+```bash packageManager="npm"
+npm install intlayer express-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer express-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer express-intlayer
+```
+
+### Configure tsconfig.json
+
+In order to use Intlayer with TypeScript, ensure your `tsconfig.json` is set up to support ES modules. You can do this by setting the `module` and `moduleResolution` options to `nodenext`.
+
+```json5 fileName="tsconfig.json"
+{
+  compilerOptions: {
+    module: "nodenext",
+    moduleResolution: "nodenext",
+    // ... other options
+  },
+}
+```
+
+### Setup
+
+Configure the internationalization settings by creating an `intlayer.config.ts` in your project root:
+
+```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;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+### Declare Your Content
+
+Create and manage your content declarations to store translations:
+
+```typescript fileName="src/app.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent: Dictionary = {
+  key: "app",
+  content: {
+    greet: t({
+      en: "Hello World!",
+      fr: "Bonjour le monde !",
+      es: "¡Hola Mundo!",
+    }),
+  },
+};
+
+export default appContent;
+```
+
+> Your content declarations can be defined anywhere in your application as soon as they are included into the `contentDir` directory (by default, `./src`). And match the content declaration file extension (by default, `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
+
+> For more details, refer to the [content declaration documentation](/doc/concept/content).
+
+### Express Middleware Setup
+
+Integrate the `express-intlayer` middleware into your NestJS application to handle internationalization:
+
+```typescript fileName="src/app.module.ts" codeFormat="typescript"
+import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
+import { AppController } from "./app.controller";
+import { AppService } from "./app.service";
+import { intlayer } from "express-intlayer";
+
+@Module({
+  imports: [],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(intlayer()).forRoutes("*"); // Apply to all routes
+  }
+}
+```
+
+### Use Translations in Your Services or Controllers
+
+You can now use the `getIntlayer` function to access translations in your services or controllers:
+
+```typescript fileName="src/app.service.ts" codeFormat="typescript"
+import { Injectable } from "@nestjs/common";
+import { getIntlayer } from "express-intlayer";
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return getIntlayer("app").greet;
+  }
+}
+```
+
+### Compatibility
+
+`express-intlayer` is fully compatible with:
+
+- [`react-intlayer`](/doc/packages/react-intlayer) for React applications
+- [`next-intlayer`](/doc/packages/next-intlayer) for Next.js applications
+- [`vite-intlayer`](/doc/packages/vite-intlayer) for Vite applications
+
+It also works seamlessly with any internationalization solution across various environments, including browsers and API requests. You can customize the middleware to detect locale through headers or cookies:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Other configuration options
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+By default, `express-intlayer` will interpret the `Accept-Language` header to determine the client's preferred language.
+
+> For more information on configuration and advanced topics, visit our [documentation](/doc/concept/configuration).
+
+### Configure TypeScript
+
+`express-intlayer` leverages the robust capabilities of TypeScript to enhance the internationalization process. TypeScript's static typing ensures that every translation key is accounted for, reducing the risk of missing translations and improving maintainability.
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png)
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png)
+
+Ensure the autogenerated types (by default at ./types/intlayer.d.ts) are included in your tsconfig.json file.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Your existing TypeScript configurations
+  include: [
+    // ... Your existing TypeScript configurations
+    ".intlayer/**/*.ts", // Include the auto-generated types
+  ],
+}
+```
+
+### VS Code Extension
+
+To improve your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
+
+[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+This extension provides:
+
+- **Autocompletion** for translation keys.
+- **Real-time error detection** for missing translations.
+- **Inline previews** of translated content.
+- **Quick actions** to easily create and update translations.
+
+For more details on how to use the extension, refer to the [Intlayer VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
+
+### Git Configuration
+
+It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
+
+To do this, you can add the following instructions to your `.gitignore` file:
+
+```plaintext fileName=".gitignore"
+# Ignore the files generated by Intlayer
+.intlayer
+```
+
+## Doc History
+
+| Version | Date       | Changes     |
+| ------- | ---------- | ----------- |
+| 5.8.0   | 2025-09-09 | Initial doc |

package/docs/en/intlayer_with_nextjs_page_router.md

@@ -15,7 +15,7 @@ slugs:
   - doc
   - environment
   - nextjs
-  - next-with-Page-Router
+  - next-with-page-router
 ---
 
 # Getting Started Internationalizing (i18n) with Intlayer and Next.js using Page Router