@intlayer/docs 5.5.8

package/en/per_locale_file.md

@@ -0,0 +1,297 @@
+# Declaration of `Per-Locale` Content Declaration in Intlayer
+
+Intlayer supports two ways to declare multilingual content:
+
+- Single file with all translations
+- One file per locale (per-locale format)
+
+This flexibility enables:
+
+- Easy migration from other i18n tools
+- Support for automated translation workflows
+- Clear organization of translations into separate, locale-specific files
+
+## Single File with Multiple Translations
+
+This format is ideal for:
+
+- Quick iteration in code.
+- Seamless integration with the CMS.
+
+This is the recommended approach for most use cases. It centralizes translations, making it easy to iterate and integrate with the CMS.
+
+```tsx fileName="hello-world.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+};
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.content.cjs" contentDeclarationFormat="json"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  content: {
+    multilingualContent: t({
+      en: "Title of my component",
+      es: "Título de mi componente",
+    }),
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```json fileName="hello-world.content.ts" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "content": {
+    "multilingualContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Title of my component",
+        "es": "Título de mi componente"
+      }
+    }
+  }
+}
+```
+
+> Recommended: This format is best when using Intlayer's visual editor or managing translations directly in the code.
+
+## Per-Locale Format
+
+This format is useful when:
+
+- You want to version or override translations independently.
+- You're integrating machine or human translation workflows.
+
+You can also split translations into individual locale files by specifying the locale field:
+
+```tsx fileName="hello-world.en.content.ts" contentDeclarationFormat="typescript"
+import { t, Locales, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // Important
+  content: { multilingualContent: "Title of my component" },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.ts" contentDeclarationFormat="typescript"
+import { t, Locales, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // Important
+  content: { multilingualContent: "Título de mi componente" },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.en.content.mjs" contentDeclarationFormat="esm"
+import { t, Locales } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // Important
+  content: { multilingualContent: "Title of my component" },
+};
+
+export default helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.mjs" contentDeclarationFormat="esm"
+import { t, Locales } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // Important
+  content: { multilingualContent: "Título de mi componente" },
+};
+
+export default helloWorldContent;
+```
+
+```js fileName="hello-world.en.content.cjs" contentDeclarationFormat="commonjs"
+const { t, Locales } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH, // Important
+  content: {
+    multilingualContent: "Title of my component",
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```tsx fileName="hello-world.es.content.cjs" contentDeclarationFormat="commonjs"
+const { t, Locales } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.SPANISH, // Important
+  content: {
+    multilingualContent: "Título de mi componente",
+  },
+};
+
+module.exports = helloWorldContent;
+```
+
+```json5 fileName="hello-world.en.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "locale": "en", // Important
+  "content": {
+    "multilingualContent": "Title of my component",
+  },
+}
+```
+
+```json5 fileName="hello-world.es.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "locale": "es", // Important
+  "content": {
+    "multilingualContent": "Título de mi componente",
+  },
+}
+```
+
+> Important: Make sure the locale field is defined. It tells Intlayer which language the file represents.
+
+> Note: In both cases, the content declaration file must follow the naming pattern `*.content.{ts,tsx,js,jsx,mjs,cjs,json}` to be recognized by Intlayer. The `.[locale]` suffix is optional and used only as a naming convention.
+
+## Mixing Formats
+
+You can combine both declaration approaches for the same content key. For example:
+
+- Declare your base content statically in a file like index.content.ts.
+- Add or override specific translations in separate files such as index.fr.content.ts or index.content.json.
+
+This setup is especially useful when:
+
+- You want to define the initial content structure in code.
+- You plan to enrich or complete translations later using the CMS or automated tools.
+
+```bash codeFormat="typescript"
+.
+└── Components
+    └── MyComponent
+        ├── index.content.ts
+        ├── index.content.json
+        └── index.ts
+```
+
+### Example
+
+Here a multilingual content declaration file:
+
+```tsx fileName="Components/MyComponent/index.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "hello-world",
+  locale: Locales.ENGLISH,
+  content: {
+    multilingualContent: "Title of my component",
+    projectName: "My project",
+  },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```json fileName="Components/MyComponent/index.content.json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "content": {
+    "multilingualContent": {
+      "nodeType": "translation",
+      "translation": {
+        "fr": "Titre de mon composant",
+        "es": "Título de mi componente"
+      }
+    }
+  }
+}
+```
+
+Intlayer merges multilingual and per-locale files automatically.
+
+```tsx fileName="Components/MyComponent/index.ts"
+import { getIntlayer, Locales } from "intlayer";
+
+const intlayer = getIntlayer("hello-world"); // Default locale is ENGLISH, so it will return the ENGLISH content
+
+console.log(JSON.stringify(intlayer, null, 2));
+// Result:
+// {
+//  "multilingualContent": "Title of my component",
+//  "projectName": "My project"
+// }
+
+const intlayer = getIntlayer("hello-world", Locales.SPANISH);
+
+console.log(JSON.stringify(intlayer, null, 2));
+// Result:
+// {
+//  "multilingualContent": "Título de mi componente",
+//  "projectName": "My project"
+// }
+
+const intlayer = getIntlayer("hello-world", Locales.FRENCH);
+
+console.log(JSON.stringify(intlayer, null, 2));
+// Result:
+// {
+//  "multilingualContent": "Titre de mon composant",
+//  "projectName": "My project"
+// }
+```
+
+### Automatic Translation Generation
+
+Use the [intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.md) to auto-fill missing translations based on your preferred services.

package/en/privacy_notice.md

@@ -0,0 +1,61 @@
+# Intlayer Privacy Notice
+
+## Introduction
+
+At Intlayer, we take privacy seriously. This notice explains how we handle information collected through our website and CMS.
+
+## Contact
+
+If you have any questions or concerns about privacy, please contact us at the following address: [contact@intlayer.org](mailto:contact@intlayer.org).
+
+## Use of Cookies and Tracking Technologies
+
+We use **Google Analytics** and the **Meta (Facebook) Pixel** to analyze the use of our website and improve our services. These tools generate statistics and other information about the website using cookies stored on users' devices.
+
+For more information:
+
+- [Google's privacy policy](https://policies.google.com/privacy)
+- [Meta’s privacy policy](https://www.facebook.com/privacy/policy)
+
+## Authentication and User Data
+
+Access to the Intlayer CMS requires user authentication. We offer both email/password authentication and third-party sign-in via **Google** and **GitHub**.
+
+During the authentication process, we collect:
+
+- Email address
+- Display name (or chosen name)
+
+Users may also access the CMS via access tokens linked to their account. These tokens are tied to the same authentication data.
+
+## Data Storage and Security
+
+User authentication data is stored in a **MongoDB database** hosted on **cloud.mongodb.com**:
+
+- **Region:** AWS / Oregon (us-west-2)
+- **Type:** Replica Set (3 nodes)
+- **Password Security:** All passwords are hashed using industry-standard practices.
+
+We do not store any unnecessary personal data beyond what is required for authentication and secure CMS access.
+
+## Data Sharing with Third Parties
+
+We do **not** sell or share your personal data with third parties, except as required for analytics (Google Analytics, Facebook Pixel) or as part of the authentication process (Google or GitHub sign-in).
+
+## Users' Rights
+
+As a user, you have the right to:
+
+- Access the personal data we hold about you
+- Request correction or deletion of your data
+- Revoke access or delete your account
+
+For any request regarding your data, contact us at [contact@intlayer.org](mailto:contact@intlayer.org).
+
+## Changes to This Notice
+
+We may update this privacy notice from time to time. Users are advised to regularly check this page to stay informed of any changes.
+
+---
+
+Let me know if you'd like a more formal tone, add GDPR/CCPA mentions, or adapt it for a legal page on your site.

package/en/roadmap.md

@@ -0,0 +1,270 @@
+# Intlayer: Feature Overview & Roadmap
+
+Intlayer is a content management and internationalization solution designed to streamline how you declare, manage, and update content across your applications. It offers powerful features such as centralized or distributed content declaration, extensive internationalization options, Markdown support, conditional rendering, TypeScript/JavaScript/JSON integration, and more. Below is a comprehensive overview of what Intlayer currently provides, followed by upcoming roadmap features.
+
+---
+
+## Current Features
+
+### 1. Content Declaration
+
+#### Centralized or Distributed
+
+- **Centralized**: Declare all your content in a single, large file at the base of your application, similar to i18next, so you can manage everything in one place.
+- **Distributed**: Alternatively, split your content into separate files at the component or feature level for better maintainability. This keeps your content close to the relevant code (components, tests, Storybook, etc.). Removing a component ensures any associated content is also removed, preventing leftover data from cluttering your codebase.
+
+> Resources:
+
+> - [Content Declaration](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/get_started.md)
+
+### 2. Internationalization
+
+- Support for **230 languages and locales** (including regional variants like French (France), English (Canada), English (UK), Portuguese (Portugal), etc.).
+- Easily manage translations for all these locales from one place.
+
+> Resources:
+
+> - [Internationalization](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/translation.md)
+
+### 3. Markdown Support
+
+- Declare content using **Markdown**, allowing you to automatically format text with paragraphs, headings, links, and more.
+- Ideal for blog posts, articles, documentation pages, or any scenario where rich text formatting is needed.
+
+> Resources:
+
+> - [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/markdown.md)
+
+### 4. External file support
+
+- Import content from external files as text format, such as TXT, HTML, JSON, YAML, or CSV.
+- Use the `file` function in Intlayer to embed external file content into a dictionary, ensuring seamless integration with the Intlayer Visual Editor and CMS.
+- Supports dynamic content updates, meaning that when the source file is modified, the content updates automatically within Intlayer.
+- Enables multilingual content management by linking language-specific Markdown files dynamically.
+
+> Resources:
+
+> - [File Content Embedding](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/file.md)
+
+### 5. Dynamic Content & Function Fetching
+
+Intlayer provides various methods to insert and manage dynamic content, ensuring flexibility and adaptability in content delivery. This includes functions for dynamic content insertion, conditional rendering, enumeration, nesting, and function fetching.
+
+1. Dynamic Content Insertion
+
+   Use the insert function to define content with placeholders ({{name}}, {{age}}, etc.).
+
+   Enables template-like content that adapts based on user input, API responses, or other dynamic data sources.
+
+   Works seamlessly with TypeScript, ESM, CommonJS, and JSON configurations.
+
+   Easily integrates with React Intlayer and Next Intlayer using useIntlayer.
+
+2. Conditional Rendering
+
+   Define content that adapts based on user-specific conditions, such as language or authentication status.
+
+   Tailor personalized experiences without duplicating content across multiple files.
+
+3. Enumeration & Pluralization
+
+   Use the enu function to define content variations based on numeric values, ranges, or custom keys.
+
+   Ensures automatic selection of the correct phrase based on a given value.
+
+   Supports ordering rules, ensuring predictable behavior.
+
+4. Nesting & Sub-Content Referencing
+
+   Use the nest function to reference and reuse content from another dictionary, reducing duplication.
+
+   Supports structured and hierarchical content management for better maintainability.
+
+5. Function Fetching
+
+   Intlayer allows content to be declared as functions, enabling both synchronous and asynchronous content retrieval.
+
+   Synchronous Functions: Content is generated dynamically at build time.
+
+   Asynchronous Functions: Fetch data from external sources (e.g., APIs, databases) dynamically.
+
+   Integration: Works with TypeScript, ESM, and CommonJS but is not supported in JSON or remote content files.
+
+### 6. Content Declaration Formats
+
+Intlayer supports **TypeScript** (also JavaScript) and **JSON** for declaring content.
+
+- **TypeScript**:
+
+  - Ensures your content structure is correct and that no translations are missing.
+  - Offers strict or more flexible validation modes.
+  - Allows dynamic data fetching from variables, functions, or external APIs.
+
+- **JSON**:
+
+  - Makes it easy to integrate with external tools (like visual editors) due to its standardized format.
+
+  > Resources:
+  >
+  > - [Content Declaration Formats](https://github.com/aymericzip/intlayer/blob/main/docs/en/dictionary/content_extention_customization.md)
+
+---
+
+## Integration with Frameworks & Environments
+
+### 1. Next.js
+
+#### a. Server and Client Components
+
+- Provides a **unified content management approach** for both server and client components.
+- Offers a built-in context for server components, simplifying implementation compared to other solutions.
+
+#### b. Metadata, Sitemaps, and robots.txt
+
+- Fetch and inject content dynamically to generate metadata, sitemaps, or `robots.txt` files.
+
+#### c. Middleware
+
+- Add a middleware to **redirect users** to content based on their preferred language.
+
+#### d. Turbopack and Webpack Compatibility
+
+- Fully compatible with the new Next.js Turbopack as well as traditional Webpack.
+
+> Resources:
+
+> - [Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_nextjs_15.md)
+
+### 2. Vite
+
+- Similar to Next.js, you can integrate Intlayer with Vite and use a **middleware** to redirect users to content based on their preferred language.
+
+> Resources:
+
+> - [Vite](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_vite+react.md)
+
+### 3. Express
+
+- Manage content and internationalize backend services built on Express.
+- Personalize emails, error messages, push notifications, and more with localized text.
+
+> Resources:
+
+> - [Express](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_express.md)
+
+### 4. React Native
+
+- Integrate Intlayer with React Native to manage content and internationalize your mobile applications.
+- Supports both iOS and Android platforms.
+
+> Resources:
+
+> - [React Native](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_react_native.md)
+
+### 5. Lynx
+
+- Integrate Intlayer with Lynx to manage content and internationalize your mobile applications.
+- Supports both iOS and Android platforms.
+
+> Resources:
+
+> - [Lynx](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_with_lynx.md)
+
+---
+
+## Visual Editors and CMS
+
+### 1. Local Visual Editor
+
+- A **free, local visual editor** that lets you edit your application content by directly selecting elements on the page.
+- Integrates AI features to help:
+  - Generate or fix translations
+  - Check syntax and spelling
+  - Suggest improvements
+- Can be hosted locally or deployed on a remote server.
+
+> Resources:
+
+> - [Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_visual_editor.md)
+
+### 2. Intlayer CMS (Remote)
+
+- A **hosted CMS** solution that allows you to manage application content online, without touching your codebase.
+- Provides AI-assisted features for declaring content, managing translations, and fixing syntax or spelling errors.
+- Interact with your content via your live application interface.
+
+> Resources:
+
+> - [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_CMS.md)
+
+---
+
+## Intlayer CLI
+
+- **Audit and Translation Generation**: Run audits on your content files to generate missing translations or identify unused ones.
+- **Remote Interaction**: Publish your local content to the remote CMS or fetch remote content to integrate into your local application.
+- Useful for **CI/CD pipelines**, ensuring your content is always synchronized with your code.
+
+> Resources:
+
+> - [CLI](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.md)
+
+---
+
+## Environments
+
+- Use **environment variables** to configure Intlayer differently across production, testing, and local environments.
+- Define which visual editor or remote CMS project to target depending on your environment.
+
+---
+
+## Hot Content Updates
+
+- When using remote dictionaries and the Intlayer CMS, you can **update your application’s content on the fly**, without needing to redeploy.
+
+> Resources:
+
+> - [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_CMS.md)
+
+---
+
+## Upcoming Features
+
+### 1. A/B Testing & Personalization
+
+- **Multivariate Testing**: Test different versions of a given piece of content to see which performs best (e.g., higher click rate).
+- **Data-Driven Personalization**: Display different content based on user demographics (gender, age, location, etc.), or other behavior patterns.
+- **Automated Iteration**: Allow AI to automatically test multiple versions and either pick the top performer or recommend options for admin approval.
+
+### 2. Versioning
+
+- Restore previous versions of your content with **content versioning**.
+- Track changes over time and revert to earlier states if needed.
+
+### 3. Automatic Translation
+
+- For remote CMS users, **one-click translation generation** for any supported language.
+- The system would generate translations in the background and then prompt you for validation or edits.
+
+### 4. SEO Enhancements
+
+- Tools to **analyze keywords**, user search intent, and emerging trends.
+- Suggest improved content for better rankings, and track long-term performance.
+
+### 5. Compatibility with More Frameworks
+
+- Efforts are underway to support **Vue, Solid, Svelte, Angular**, and more.
+- Aim to make Intlayer compatible with **any JavaScript-powered application**.
+
+### 6. IDE Extensions
+
+- Extensions for major IDEs to provide a **graphical interface** for managing local and remote translations.
+- Features could include auto-generating content declaration files for components, direct integration with the Intlayer CMS, and real-time validation.
+
+---
+
+## Conclusion
+
+Intlayer aims to be a one-stop solution for content management and internationalization. It focuses on flexibility (centralized or distributed files), broad language support, easy integration with modern frameworks and bundlers, and powerful AI-driven features. As new capabilities, such as A/B testing, versioning, and automated translations, become available, Intlayer will continue to simplify content workflows and elevate user experiences across different platforms.
+
+Stay tuned for upcoming releases, and feel free to explore the existing features to see how Intlayer can help centralize and optimize your content management processes today!