Intlayer Configuration Documentation

Overview

Intlayer configuration files allow customization of various aspects of the plugin, such as internationalization, middleware, and content handling. This document provides a detailed description of each property in the configuration.

Configuration File Support

Intlayer accepts JSON, JS, MJS, and TS configuration file formats:

• intlayer.config.ts
• intlayer.config.js
• intlayer.config.json
• intlayer.config.cjs
• intlayer.config.mjs
• .intlayerrc

Example config file

// intlayer.config.ts

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH],
  },
  content: {
    typesDir: "content/types",
  },
  middleware: {
    noPrefix: false,
  },
};

export default config;

// intlayer.config.cjs

const { Locales } = require("intlayer");

/** @type {import('intlayer').IntlayerConfig} */
const config = {
  internationalization: {
    locales: [Locales.ENGLISH],
  },
  content: {
    typesDir: "content/types",
  },
  middleware: {
    noPrefix: false,
  },
};

module.exports = config;

// .intlayerrc

{
  "internationalization": {
    "locales": ["en"],
  },
  "content": {
    "typesDir": "content/types",
  },
  "middleware": {
    "noPrefix": false,
  },
}

Configuration Reference

The following sections describe the various configuration settings available for Intlayer.

Internationalization Configuration

Defines settings related to internationalization, including available locales and the default locale for the application.

Properties

• locales:
  • Type: string[]
  • Default: ['en']
  • Description: The list of supported locales in the application.
  • Example: ['en', 'fr', 'es']

• strictMode:

  • Type: string
  • Default: required_only
  • Description: Ensure strong implementations of internationalized content using typescript.
  • Note: If set to "strict", the translation t function will require each declared locales to be defined. If one locale is missing, or if a locale is not declared in your config, it will throw an error.
  • Note: If set to "required_only", the translation t function will require each declared locales to be defined. If one locale is missing, it will throw a warning. But will accept if a locale is not declared in your config, but exists.
  • Note: If set to "loose", the translation t function will accept any existing locale.

• defaultLocale:

  • Type: string
  • Default: 'en'
  • Description: The default locale used as a fallback if the requested locale is not found.
  • Example: 'en'
  • Note: This is used to determine the locale when none is specified in the URL, cookie, or header.

Editor Configuration

Defines settings related to the integrated editor, including server port and active status.

Properties

• backendURL:

  • Type: string
  • Default: https://back.intlayer.org
  • Description: The URL of the backend server.
  • Example: http://localhost:4000

• enabled:

  • Type: boolean
  • Default: true
  • Description: Indicates if the editor is active.
  • Example: true
  • Note: Can be set using NODE_ENV, or other dedicated env variable

• clientId:

  • Type: string | undefined
  • Default: undefined
  • Description: clientId and clientSecret allow the intlayer packages to authenticate with the backend using oAuth2 authentication. An access token is used to authenticate the user related to the project. To get an access token, go to https://back.intlayer.org/dashboard/project and create an account.
  • Example: true
  • Note: Important: The clientId and clientSecret should be kept secret and not shared publicly. Please ensure to keep them in a secure location, such as environment variables.

• clientSecret:

  • Type: string | undefined
  • Default: undefined
  • Description: clientId and clientSecret allow the intlayer packages to authenticate with the backend using oAuth2 authentication. An access token is used to authenticate the user related to the project. To get an access token, go to https://back.intlayer.org/dashboard/project and create an account.
  • Example: true
  • Note: Important: The clientId and clientSecret should be kept secret and not shared publicly. Please ensure to keep them in a secure location, such as environment variables.

Middleware Configuration

Settings that control middleware behavior, including how the application handles cookies, headers, and URL prefixes for locale management.

Properties

• headerName:
  • Type: string
  • Default: 'x-intlayer-locale'
  • Description: The name of the HTTP header used to determine the locale.
  • Example: 'x-custom-locale'
  • Note: This is useful for API-based locale determination.
• cookieName:
  • Type: string
  • Default: 'intlayer-locale'
  • Description: The name of the cookie used to store the locale.
  • Example: 'custom-locale'
  • Note: Used to persist the locale across sessions.
• prefixDefault:
  • Type: boolean
  • Default: true
  • Description: Whether to include the default locale in the URL.
  • Example: false
  • Note: If false, URLs for the default locale will not have a locale prefix.
• basePath:
  • Type: string
  • Default: ''
  • Description: The base path for the application URLs.
  • Example: '/my-app'
  • Note: This affects how URLs are constructed for the application.
• serverSetCookie:
  • Type: string
  • Default: 'always'
  • Description: Rule for setting the locale cookie on the server.
  • Options: 'always', 'never'
  • Example: 'never'
  • Note: Controls whether the locale cookie is set on every request or never.
• noPrefix:
  • Type: boolean
  • Default: false
  • Description: Whether to omit the locale prefix from URLs.
  • Example: true
  • Note: If true, URLs will not contain locale information.

Content Configuration

Settings related to content handling within the application, including directory names, file extensions, and derived configurations.

Properties

• watch:
  • Type: boolean
  • Default: process.env.NODE_ENV === 'development'
  • Description: Indicates if Intlayer should watch for changes in the content declaration files in the app to rebuild the related dictionaries.
• fileExtensions:
  • Type: string[]
  • Default: ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
  • Description: File extensions to look for when building dictionaries.
  • Example: ['.data.ts', '.data.js', '.data.json']
  • Note: Customizing file extensions can help avoid conflicts.
• baseDir:
  • Type: string
  • Default: process.cwd()
  • Description: The base directory for the project.
  • Example: '/path/to/project'
  • Note: This is used to resolve all Intlayer-related directories.
• dictionaryOutput:
  • Type: string[]
  • Default: ['intlayer']
  • Description: The type of dictionary output to use, e.g., 'intlayer' or 'i18next'.
• contentDirName:
  • Type: string
  • Default: 'src'
  • Description: The name of the directory where the content is stored.
  • Example: 'data', 'content', 'locales'
  • Note: If not at the base directory level, update the contentDir.

• contentDir:

  • Type: string
  • DerivedFrom: 'baseDir' / 'contentDirName'
  • Description: The directory path where content is stored.
• resultDirName:
  • Type: string
  • Default: '.intlayer'
  • Description: The name of the directory where results are stored.
  • Example: 'outputOFIntlayer'
  • Note: If this directory is not at the base level, update resultDir.

• resultDir:

  • Type: string
  • DerivedFrom: 'baseDir' / 'resultDirName'
  • Description: The directory path for storing intermediate or output results.

• moduleAugmentationDirName:

  • Type: string
  • Default: 'types'
  • Description: Directory for module augmentation, allowing better IDE suggestions and type checking.
  • Example: 'intlayer-types'
  • Note: Be sure to include this in tsconfig.json.

• moduleAugmentationDir:

  • Type: string
  • DerivedFrom: 'baseDir' / 'moduleAugmentationDirName'
  • Description: The path for module augmentation and additional type definitions.
• dictionariesDirName:
  • Type: string
  • Default: 'dictionary'
  • Description: Directory for storing dictionaries.
  • Example: 'translations'
  • Note: If not at the result directory level, update dictionariesDir.

• dictionariesDir:

  • Type: string
  • DerivedFrom: 'resultDir' / 'dictionariesDirName'
  • Description: The directory for storing localization dictionaries.
• i18nDictionariesDirName:
  • Type: string
  • Default: 'i18n_dictionary'
  • Description: Directory for storing i18n dictionaries.
  • Example: 'translations'
  • Note: If not at the result directory level, update i18nDictionariesDir.
  • Note: Ensure the i18n dictionaries output includes i18next to build the dictionaries for i18next

• i18nDictionariesDir:

  • Type: string
  • DerivedFrom: 'resultDir' / 'i18nDictionariesDirName'
  • Description: The directory for storing i18n dictionaries.
  • Note: Ensure this directory is configured for the i18next output type.

• typeDirName:

  • Type: string
  • Default: 'types'
  • Description: Directory for storing dictionary types.
  • Example: 'intlayer-types'
  • Note: If not at the result directory level, update typesDir.

• typesDir:

  • Type: string
  • DerivedFrom: 'resultDir' / 'typeDirName'
  • Description: The directory for storing dictionary types.
• mainDirName:
  • Type: string
  • Default: 'main'
  • Description: Directory for storing main files.
  • Example: 'intlayer-main'
  • Note: If not at the result directory level, update mainDir.
• mainDir:
  • Type: string
  • DerivedFrom: 'resultDir' / 'mainDirName'
  • Description: The directory where main application files are stored.
• excludedPath:
  • Type: string[]
  • Default: ['node_modules']
  • Description: Directories excluded from content search.
  • Note: This setting is not yet used, but planned for future implementation.