docs: add doc, how intlayer works

CONTRIBUTING.md

@@ -1,5 +1,9 @@
 # Contributing to IntLayer
 
+## Understanding the project
+
+To understand the project, you can read the [documentation named "How Intlayer Works"](https://github.com/aypineau/intlayer/blob/main/docs/docs/how_works_intlayer_en.md).
+
 ## Development setup
 
 IntLayer is developed as a mono-repo using pmpm.

apps/website/src/Routes.ts

@@ -3,6 +3,7 @@ export enum PagesRoutes {
   Demo = '/demo',
   Doc = '/doc',
   Doc_GetStarted = '/doc/get_started',
+  Doc_HowWorksIntlayer = '/doc/concept/how_works_intlayer',
   Doc_Configuration = '/doc/concept/configuration',
   Doc_Interest = '/doc/concept/interest_of_intlayer',
   Doc_IntlayerEditor = '/doc/concept/intlayer_editor',

apps/website/src/app/[locale]/doc/concept/how_works_intlayer/metadata.ts

@@ -0,0 +1,56 @@
+import { type IConfigLocales, getTranslationContent } from 'intlayer';
+import type { Metadata } from 'next';
+import type { LocalParams } from 'next-intlayer';
+
+export const generateMetadata = ({
+  params: { locale },
+}: LocalParams): Metadata => {
+  const t = <T>(content: IConfigLocales<T>) =>
+    getTranslationContent(content, locale);
+
+  return {
+    title: t<string>({
+      en: 'Intlayer | How works Intlayer',
+      fr: 'Intlayer | Comment Intlayer fonctionne',
+      es: 'Intlayer | Cómo funciona Intlayer',
+    }),
+    description: t<string>({
+      en: 'Discover how Intlayer works. See the steps used by Intlayer in your application. See what does the different packages do.',
+      fr: 'Découvrez comment Intlayer fonctionne. Voir les étapes utilisées par Intlayer dans votre application. Voir ce qui fait les différents packages.',
+      es: 'Descubra cómo Intlayer funciona. Vea las pasos utilizados por Intlayer en su aplicación. Vea lo que hace los diferentes paquetes.',
+    }),
+
+    keywords: t<string[]>({
+      en: [
+        'Package',
+        'Functioning',
+        'Internationalization',
+        'Documentation',
+        'Intlayer',
+        'Next.js',
+        'JavaScript',
+        'React',
+      ],
+      fr: [
+        'Package',
+        'Fonctionnement',
+        'Internationalisation',
+        'Documentación',
+        'Intlayer',
+        'Next.js',
+        'JavaScript',
+        'React',
+      ],
+      es: [
+        'Package',
+        'Funcionamiento',
+        'Internacionalización',
+        'Documentación',
+        'Intlayer',
+        'Next.js',
+        'JavaScript',
+        'React',
+      ],
+    }),
+  };
+};

apps/website/src/app/[locale]/doc/concept/how_works_intlayer/page.tsx

@@ -0,0 +1,16 @@
+import { DocPageLayout } from '@components/DocPage/DocPageLayout';
+import { DocumentationRender } from '@components/DocPage/DocumentationRender';
+import { PageLayout } from '@layouts/PageLayout';
+import type { NextPageIntlayer } from 'next-intlayer';
+import { generateMetadata } from './metadata';
+
+export { generateMetadata };
+
+const Page: NextPageIntlayer = ({ params: { locale } }) => (
+  <PageLayout locale={locale} editorEnabled={false}>
+    <DocPageLayout activeSections={['concept', 'how_works_intlayer']}>
+      <DocumentationRender docName="how_works_intlayer" />
+    </DocPageLayout>
+  </PageLayout>
+);
+export default Page;

apps/website/src/components/DocPage/doc-page.content.ts

@@ -25,6 +25,15 @@ export const navbarContent: DeclarationContent<NavbarContent> = {
       key: 'concept',
       title: t({ fr: 'Concept', en: 'Concept', es: 'Concepto' }),
       subSections: [
+        {
+          key: 'how_works_intlayer',
+          title: t({
+            en: 'How Intlayer Works',
+            fr: 'Comment Intlayer fonctionne',
+            es: 'Cómo funciona Intlayer',
+          }),
+          url: PagesRoutes.Doc_HowWorksIntlayer,
+        },
         {
           key: 'configuration',
           title: t({

apps/website/src/components/LandingPage/AvailableTechnoSection/index.tsx

@@ -4,7 +4,7 @@ import type { FC } from 'react';
 import Nextjs from './nextjs.svg';
 import React from './reactjs.svg';
 import Vite from './vitejs.svg';
-import { ExternalLinks } from '@/Routes';
+import { PagesRoutes } from '@/Routes';
 
 export const AvailableTechnoSection: FC = () => {
   const { text, react, vite, nextjs } = useIntlayer('available-techno-section');
@@ -14,21 +14,21 @@ export const AvailableTechnoSection: FC = () => {
       <span className="text-neutral">{text}</span>
       <div className="flex h-28 w-3/4 flex-row justify-evenly gap-6 p-6">
         <Link
-          href={ExternalLinks.IntlayerWithReact}
+          href={PagesRoutes.Doc_Environment_CRA}
           className="grow-0"
           aria-label={react.label.value}
         >
           <React className="size-full max-h-full" />
         </Link>
         <Link
-          href={ExternalLinks.IntlayerWithNextjs}
+          href={PagesRoutes.Doc_Environment_NextJS}
           className="grow-0"
           aria-label={nextjs.label.value}
         >
           <Nextjs className="size-full max-h-full" />
         </Link>
         <Link
-          href={ExternalLinks.IntlayerWithVite}
+          href={PagesRoutes.Doc_Environment_ViteAndReact}
           className="grow-0"
           aria-label={vite.label.value}
         >

apps/website/src/components/LandingPage/LandingSection/ActionButtons.tsx

@@ -4,7 +4,7 @@ import { Button } from '@intlayer/design-system';
 import { useRouter } from 'next/navigation';
 import { useIntlayer } from 'next-intlayer';
 import type { FC } from 'react';
-import { ExternalLinks } from '@/Routes';
+import { ExternalLinks, PagesRoutes } from '@/Routes';
 
 export const ActionButtons: FC = () => {
   const {
@@ -18,7 +18,7 @@ export const ActionButtons: FC = () => {
       <Button
         label={secondaryLabel.value}
         variant="outline"
-        onClick={() => router.push(ExternalLinks.InterestOfIntlayer)}
+        onClick={() => router.push(PagesRoutes.Doc_Interest)}
         size="lg"
         color="text"
         className="w-full md:w-auto"

docs/assets/packages_dependency_graph.txt

@@ -0,0 +1,28 @@
+website: https://playground.diagram.codes/d/graph
+
+"inltayer" as a
+"react-intlayer" as b
+"intlayer-cli" as c
+"next-intlayer" as d
+"intlayer-editor" as e
+"@intlayer/chokidar" as f
+"@intlayer/config" as g
+"@intlayer/core" as h
+"@intlayer/dictionaries-entry" as i
+"@intlayer/webpack" as j
+"@intlayer/cli" as k
+"nextjs website" as l
+"react website" as m
+
+
+a->l,m
+b->d,m
+c->
+d->l
+e->l
+f->b,c,d,e,g,h,j
+g->b,c,d,e,h
+h->b,c,d,e
+i->e,j
+j->d
+k->c

docs/docs/configuration_en.md

@@ -255,7 +255,7 @@ Settings related to content handling within the application, including directory
 
 - **i18nDictionariesDirName**:
   - _Type_: `string`
-  - _Default_: `'i18_dictionary'`
+  - _Default_: `'i18n_dictionary'`
   - _Description_: Directory for storing i18n dictionaries.
   - _Example_: `'translations'`
   - _Note_: If not at the result directory level, update `i18nDictionariesDir`.

docs/docs/configuration_es.md

@@ -246,7 +246,7 @@ Name'`
   - _Descripción_: El directorio para almacenar diccionarios de localización.
 - **i18nDictionariesDirName**:
   - _Tipo_: `string`
-  - _Predeterminado_: `'i18_dictionary'`
+  - _Predeterminado_: `'i18n_dictionary'`
   - _Descripción_: Directorio para almacenar diccionarios i18n.
   - _Ejemplo_: `'translations'`
   - _Nota_: Si no está en el nivel del directorio de resultados, actualiza `i18nDictionariesDir`.

docs/docs/configuration_fr.md

@@ -258,7 +258,7 @@ Paramètres relatifs à la gestion du contenu au sein de l'application, y compri
 
 - **i18nDictionariesDirName** :
   - _Type_ : `string`
-  - _Défaut_ : `'i18_dictionary'`
+  - _Défaut_ : `'i18n_dictionary'`
   - _Description_ : Répertoire pour stocker les dictionnaires i18n.
   - _Exemple_ : `'translations'`
   - _Note_ : Si ce répertoire n'est pas au niveau des résultats, mettez à jour `i18nDictionariesDir`.

docs/docs/how_works_intlayer_en.md

@@ -0,0 +1,88 @@
+# How Intlayer Works
+
+## Overview
+
+The role of Intlayer is to interpret JavaScript content declaration files into dictionaries.
+
+For this, Intlayer goes through several steps:
+
+1. Declaration of content files
+
+   - Content files can be defined in various formats, such as TypeScript, ECMAScript, CommonJS, or JSON.
+   - Content files can be defined everywhere in the project, which allows for better maintenance and scalability. It is important to respect the file extension conventions for content files. This extension is by default `*.content.{js|cjs|mjs|ts|tsx|json}`, but it can be modified in the [configuration file](https://github.com/aypineau/intlayer/blob/main/docs/docs/configuration_en.md).
+
+2. Generation of dictionaries
+
+   - Dictionaries are generated from content files. By default, intlayer dictionaries are generated in the `.intlayer/dictionary` directory of the project.
+   - Two types of dictionaries can be generated: intlayer dictionaries and i18n dictionaries (beta).
+
+3. Generation of dictionary types
+
+   - Dictionary types are generated from intlayer dictionaries. By default, intlayer dictionary types are generated in the `.intlayer/types` directory of the project.
+
+4. Generation of Intlayer module augmentation
+
+   - Intlayer [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) is a TypeScript feature that allows you to define additional types for Intlayer. This makes development experience easier by suggesting available arguments or required arguments.
+     Among the types generated, intlayer dictionary types or even language configuration types are added to the `types/intlayer.d.ts` file, and used by other packages. To do this, it is necessary that the `tsconfig.json` file is configured to include the `.intlayer/types` directory of the project.
+
+5. Content file monitoring
+
+   - Content files are monitored to be regenerated each time they are modified.
+
+6. Dictionary interpretation
+   - Dictionaries are finally interpreted to be used in applications.
+
+## Packages
+
+Intlayer is composed of several packages, each with a specific role in the translation process. Here is a graphical representation of the structure of this package:
+
+![packages of intlayer](https://github.com/aypineau/intlayer/blob/main/docs/assets/packages_dependency_graph.svg)
+
+### intlayer
+
+The `intlayer` package is used in applications to declare content in content files.
+
+### react-intlayer
+
+The `react-intlayer` package is used to interpret intlayer dictionaries and make them usable in React applications.
+
+### next-intlayer
+
+The `next-intlayer` package is used as a layer on top of `react-intlayer` to make intlayer dictionaries usable in Next.js applications. It integrates essential features to make Intlayer work in a Next.js environment, such as translation middleware, routing, or the `next.config.js` file configuration.
+
+### intlayer-editor
+
+The `intlayer-editor` package is used to allow the use of the visual editor. This package, optional can be installed in applications and will be used by the `react-intlayer` package.
+It consists of two parts: the server and the client.
+
+The client contains UI elements that will be used by `react-intlayer`.
+
+The server, based on Express, is used to receive the editor visual requests and manage or modify content files.
+
+### intlayer-cli
+
+The `intlayer-cli` package can be used to generate dictionaries using the `npx intlayer transpile` command.
+
+### @intlayer/core
+
+The `@intlayer/core` package is the master Intlayer package. It contains translation and dictionary management functions. `@intlayer/core` is multiplatform and is used by other packages to perform interpretation of dictionaries.
+
+### @intlayer/config
+
+The `@intlayer/config` package is used to configure Intlayer settings, such as available languages, nextjs middleware parameters or the integrated editor settings.
+
+### @intlayer/webpack
+
+The `@intlayer/webpack` package is used to add compilation plugins to Next.js and React.
+
+### @intlayer/cli
+
+The `@intlayer/cli` package is used to ensure uniformity of all intlayer CLI commands.
+
+### @intlayer/dictionaries-entry
+
+The `@intlayer/dictionaries-entry` package is a package that only returns the entry path of the intlayer dictionaries. Since the filesystem search is impossible from the browser, using bundlers like Webpack or Rollup to retrieve the entry path of the dictionaries is not possible. This package aims to be aliased.
+
+### @intlayer/chokidar
+
+The `@intlayer/chokidar` package is used to monitor content files and regenerate the modified dictionary at each modification.

docs/docs/how_works_intlayer_es.md

@@ -0,0 +1,88 @@
+# Cómo funciona Intlayer
+
+## Visión General
+
+El rol de Intlayer es interpretar los archivos de declaración de contenido de JavaScript en diccionarios.
+
+Para ello Intlayer realiza varias pasos:
+
+1. Declaración de archivos de contenido
+
+   - Los archivos de contenido se pueden definir en diferentes formatos, como TypeScript, ECMAScript, CommonJS o JSON.
+   - Los archivos de contenido se pueden definir en cualquier lugar del proyecto, lo que permite una mejor gestión de la mantenimiento y la escalabilidad. Es importante respetar las convenciones de extensión de archivos de contenido. Esta extensión por defecto es `*.content.{js|cjs|mjs|ts|tsx|json}`, pero puede ser modificada en el [archivo de configuración](https://github.com/aypineau/intlayer/blob/main/docs/docs/configuration_es.md).
+
+2. Generación de diccionarios
+
+   - Los diccionarios se generan a partir de los archivos de contenido. Por defecto, los diccionarios intlayer se generan en el directorio `.intlayer/dictionary` del proyecto.
+   - Dos tipos de diccionarios pueden ser generados: los diccionarios intlayer y los diccionarios i18n (beta).
+
+3. Generación de tipos de diccionarios
+
+   - Los tipos de diccionarios se generan a partir de los diccionarios intlayer. Por defecto, los tipos de diccionarios intlayer se generan en el directorio `.intlayer/types` del proyecto.
+
+4. Generación de la augmentación de módulos de Intlayer
+
+   - Intlayer [augmentación de módulos](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) es una característica de TypeScript que le permite definir tipos adicionales para Intlayer. Esto facilita la experiencia de desarrollo al sugerir argumentos disponibles o requeridos.
+     Entre los tipos generados, los tipos de diccionarios intlayer o incluso los tipos de configuración de idioma se agregan al archivo `types/intlayer.d.ts`, y se utilizan por otros paquetes. Para hacer esto, es necesario que el archivo `tsconfig.json` esté configurado para incluir el directorio `.intlayer/types` del proyecto.
+
+5. Monitoreo de archivos de contenido
+
+   - Los archivos de contenido se monitorean para ser regenerados cada vez que se modifican.
+
+6. Interpretación de diccionarios
+   - Los diccionarios finalmente se interpretan para ser usados en aplicaciones.
+
+## Paquetes
+
+Intlayer se compone de varios paquetes, cada uno con un rol específico en el proceso de traducción. Aquí hay una representación gráfica de la estructura de este paquete:
+
+![paquetes de intlayer](https://github.com/aypineau/intlayer/blob/main/docs/assets/packages_dependency_graph.svg)
+
+### intlayer
+
+El paquete `intlayer` se utiliza en aplicaciones para declarar contenido en archivos de contenido.
+
+### react-intlayer
+
+El paquete `react-intlayer` se utiliza para interpretar diccionarios intlayer y hacerlos usables en aplicaciones React.
+
+### next-intlayer
+
+El paquete `next-intlayer` se utiliza como una capa sobre `react-intlayer` para hacer diccionarios intlayer usables en aplicaciones Next.js. Integra características esenciales para hacer Intlayer funcionar en un entorno Next.js, como middleware de traducción, rutas o la configuración del archivo `next.config.js`.
+
+### intlayer-editor
+
+El paquete `intlayer-editor` se utiliza para permitir el uso del editor visual. Este paquete, opcional se puede instalar en aplicaciones y se utilizará por el paquete `react-intlayer`.
+Consiste en dos partes: el servidor y el cliente.
+
+El cliente contiene elementos UI que se utilizarán por `react-intlayer`.
+
+El servidor, basado en Express, se utiliza para recibir las solicitudes del editor visual y administrar o modificar archivos de contenido.
+
+### intlayer-cli
+
+El paquete `intlayer-cli` se puede utilizar para generar diccionarios utilizando el comando `npx intlayer transpile`.
+
+### @intlayer/core
+
+El paquete `@intlayer/core` es el paquete maestro de Intlayer. Contiene funciones de traducción y gestión de diccionarios. `@intlayer/core` es multiplataforma y se utiliza por otros paquetes para realizar la interpretación de diccionarios.
+
+### @intlayer/config
+
+El paquete `@intlayer/config` se utiliza para configurar la configuración de Intlayer, como idiomas disponibles, parámetros de middleware de Next.js o la configuración del editor integrado.
+
+### @intlayer/webpack
+
+El paquete `@intlayer/webpack` se utiliza para agregar complementos de compilación a Next.js y React.
+
+### @intlayer/cli
+
+El paquete `@intlayer/cli` se utiliza para garantizar la uniformidad de todos los comandos de CLI de intlayer.
+
+### @intlayer/dictionaries-entry
+
+El paquete `@intlayer/dictionaries-entry` es un paquete que solo devuelve la ruta de entrada de los diccionarios intlayer. Dado que la búsqueda de sistema de archivos es imposible desde el navegador, utilizar los bundlers como Webpack o Rollup para recuperar la ruta de entrada de los diccionarios no es posible. Este paquete pretende ser aliasado.
+
+### @intlayer/chokidar
+
+El paquete `@intlayer/chokidar` se utiliza para monitorear los archivos de contenido y regenerar el diccionario modificado en cada modificación.