Skip to main content

Configuration

NextGlobeGen can be configured through an i18n.config.ts file in the root of your project directory with a default export.

i18n.config.ts
import { Config } from "next-globe-gen";

const config: Config = {
  /* config options here */
};

export default config;

The location of the configuration file can be altered by giving the path to the configuration file as an argument to the NextGlobeGen plugin in next.config.ts file.

next.config.ts
import type { NextConfig } from "next";
import { withNextGlobeGenPlugin } from "next-globe-gen/plugin";

const withNextGlobeGen = withNextGlobeGenPlugin("./configs/next-globe-gen.ts");

const nextConfig: NextConfig = {
  /* Next.js config options here */
};

export default withNextGlobeGen(nextConfig);

Options​

This section documents all the available configuration options.

locales​

An array of locales that the application supports. At least one locale needs to be provided.

const config: Config = {
  locales: ["en", "fi"],
};

defaultLocale​

A locale that will be used as a default locale. Should be one of the provided locales.

const config: Config = {
  locales: ["en", "fi"],
  defaultLocale: "en",
};

prefixDefaultLocale​

A boolean value indicating if the default locale version of the site should be served from locale-prefixed path or from the root.

const config: Config = {
  prefixDefaultLocale: false, // Default: true
};

Routes​

Options under routes namespace affect how localized routes are generated.

originDir​

A path to a directory where the origin routes are located. The NextGlobeGen pugin watches this directory for changes and regenerates the routes when necessary.

const config: Config = {
  routes: {
    originDir: "./_app", // Default: "./src/_app"
  },
};

localizedDir​

A path to a directory where the localized routes will be generated.

const config: Config = {
  routes: {
    localizedDir: "./app/(i18n)", // Default: "./src/app/(i18n)"
  },
};

skipLanguageAlternatesMetadata​

NextGlobeGen package injects language alternates to the metadata objects exported or returned by generateMetadata functions for all page routing files.

Option skipLanguageAlternatesMetadata is used to configure if the automatic alternate language URLs metadata generation should be skipped or not.

const config: Config = {
  routes: {
    skipLanguageAlternatesMetadata: true, // Default: false
  },
};

Domains​

Using the domains option enables the domain based routing. Is receives all domain spesific locale configuration objects as an array. Each object defines which locales are served from the defined domain and which locale is used as a default locale.

When domains option is given, the root level locales and defaultLocale options must be removed.

const config: Config = {
  domains: [
    {
      domain: "fi.example.com",
      locales: ["fi"],
      defaultLocale: "fi",
    },
    {
      domain: "en.example.com",
      locales: ["en", "en-US"],
      defaultLocale: "en",
      prefixDefaultLocale: true, // Default: false
    },
  ],
};

Messages​

Options under messages namespace affect how messages are loaded and handled in the application.

originDir​

A path to a directory where the message files are located. The NextGlobeGen pugin watches this directory for changes and recompiles the messages when necessary.

const config: Config = {
  messages: {
    originDir: "./messages", // Default: "./src/messages"
  },
};

keyExtractionDirs​

Directories to scan for translation key usage. The generator uses an SWC plugin to statically analyze your source files and extract all translation keys.

const config: Config = {
  messages: {
    keyExtractionDirs: ["./src"], // Default: ["./src"]
  },
};
Disabling extraction

Set to an empty array [] to disable automatic key extraction.

pruneUnusedKeys​

When enabled, keys that are no longer found in your source code will be removed from message files during extraction.

const config: Config = {
  messages: {
    pruneUnusedKeys: true, // Default: false
  },
};
warning

Be careful when enabling this option. Keys that are used dynamically (e.g., t(variable)) cannot be statically extracted and will be pruned. Use whitelistedKeys to protect such keys.

whitelistedKeys​

A regular expression or array of regular expressions that protect matching keys from being pruned, even if they're not found in source code.

const config: Config = {
  messages: {
    pruneUnusedKeys: true,
    whitelistedKeys: [
      /^dynamic\./, // Protect all keys under "dynamic" namespace
      /^server\.errors\./, // Protect server error messages
    ],
  },
};

loadMessageEntries​

An async function that loads message entries for a given locale. Must return an array of MessageEntry objects containing the key, message, and optional description.

const config: Config = {
  messages: {
    loadMessageEntries(
      locale: string,
    ): Promise<MessageEntry[]> | MessageEntry[] {
      /* fetch messages for example from an external provider */
    },
  },
};
MessageEntry type
type MessageEntry = {
  key: string; // Dot-separated key (e.g., "common.buttons.submit")
  message: string; // The message content (ICU format supported)
  description?: string; // Optional description for translators
};
Default message loading

By default messages are loaded from <locale>.json and <locale>/<filename>.json files from the directory specified by the originDir option.

The messages from the <locale>/<filename>.json file are put under <filename> namespace. An expection to this rule are the messages from the <locale>/index.json file, which are not put under any namespace.

YAML Support

The package supports also messages in YAML files using .yaml or .yml extensions.

writeMessageEntries​

An async function that persists updated message entries for a given locale. Used during key extraction to write discovered keys back to your message store.

const config: Config = {
  messages: {
    writeMessageEntries(
      locale: string,
      messageEntries: MessageEntry[],
    ): Promise<void> | void {
      /* store messages for example to an external provider */
    },
  },
};

clientKeys​

A regular expression or an array of regular expressions that filter out which messages are provided to the client. A message will be provided to the client if it's key matches to any of the given regular expressions.

const config: Config = {
  messages: {
    // Provide only messages in the `client` namespace to the client
    clientKeys: /^client\./,
  },
};
Message key

Key of the message is it's full object dot notation syntax as a string, possibly prefixed with a filename namespace. (i.e. filename.deeply.nested.object.key)

The clientKeys option allows full regex so excluding some of the messages is also possible using negative lookaheads.

By default all messages are sent to the client. If you want to exclude all messages from being provided to the client, use an empty array.

Reducing payload

This option is helpful if you would like to reduce the payload of the responses by sending fewer of the messages to the client.

formats​

Object which is used to extend or override the predefined format options.

const config: Config = {
  messages: {
    formats: {
      number: {
        onedigit: {
          minimumFractionDigits: 1,
          maximumFractionDigits: 1,
        },
      },
      date: {
        withtime: {
          dateStyle: "long",
          timeStyle: "short",
        },
      },
      time: {
        withdate: {
          dateStyle: "short",
          timeStyle: "medium",
        },
      },
    },
  },
};