next-i18n-auth

Next-i18n-auth

Automation Scripts Documentation

Overview

The Next-i18n-auth system is a comprehensive internationalization (i18n) toolkit that streamlines translation management in large-scale Next.js applications. It automates namespace generation, key extraction, translation updates, and TypeScript typing — all powered by a Gulp-based workflow.

How to Use the Gulp Tasks

Note: See the following libraries for more information about the Gulp scripts.

Key Features

1. Automatic Namespace and Key Generation

2. Translation File Management

3. Dynamic Translation Generation

next-i18n-auth Preview

4. TypeScript Integration

Available Gulp Tasks

1. smart-i18n (default task)

2. smart-i18n generate-namespaces

3. smart-i18n generate-templates

Generate templates log-1 Generate templates log-2

Note: See translation section for more information about the translation keys and organization.

4. smart-i18n generate-types

5. smart-i18n generate-translations [-l, --lang <language>]

Translation process

6. smart-i18n watch

Watch

7. smart-i18n-react create-feature [-n, --name <feature-name>] [--js]

Create feature task output

8. smart-i18n help

Help Help

9. smart-i18n-react help

Help

💡 Tip: It’s recommended to run smart-i18n (default task) before each deployment to ensure that your namespaces, templates, and types are fully synced.

Workflow

  1. Namespace Generation: Run smart-i18n generate-namespaces to scan your codebase and update namespace definitions.
  2. Key Extraction: Run smart-i18n generate-templates to extract new translation keys from your codebase.
  3. Type Generation: Run smart-i18n generate-types to generate TypeScript types for the translations.
  4. Translation: Run smart-i18n generate-translations to automatically translate missing keys.
  5. Watching: Use smart-i18n watch to monitor file changes and regenerate namespaces, templates, and types automatically.
  6. Feature Creation: Use smart-i18n-react create-feature to create a new feature with the necessary boilerplate.

Note See Script aliases to see mapped shortcuts. Script Mappings

Configuration

i18next.config.json

This is the configuration file used by the Next-i18n-auth system to define how translations should be managed.

{
  // Path to your i18n configuration file
  "configFilePath": "src/i18n/lib/config.ts",

  // Directory where all translation files are stored
  "localesDirectory": "src/i18n/locales",

  // Path for generated namespaces
  "generatedNamespacesPath": "src/i18n/generated/namespaces.ts",

  // Path for generated TypeScript types
  "generatedTypesPath": "src/i18n/generated/types.d.ts",

  // Whether to preserve or remove unused keys
  "keepUnusedKeys": true,

  // Patterns for files to include in the translation process
  "includePatterns": [
    "src/app/**/*.{jsx,tsx}",
    "src/core/components/**/*.{js,jsx,ts,tsx}",
    "src/core/hooks/**/*.{js,jsx,ts,tsx}",
    "src/shared/components/**/*.{js,jsx,ts,tsx}",
    "src/shared/hooks/**/*.{js,jsx,ts,tsx}",
    "src/shared/services/api.{js,ts}", // look this file to specify dynamic backend error codes
    "src/features/*/components/**/*.{js,jsx,ts,tsx}",
    "src/features/*/hooks/**/*.{js,jsx,ts,tsx}",
    "src/features/*/lib/zod.{js,ts}"
  ],

  // Patterns for files to exclude from the translation process
  "excludePatterns": [
    "src/**/*.d.ts",   // Exclude TypeScript definition files
    "**/node_modules/**", // Exclude dependencies in node_modules
    "src/i18n/**",  // Exclude existing i18n files (we're handling these separately)
    "src/app/api/**", // Exclude API files
    "src/shared/components/ui/**", // Exclude UI component files
    "src/shared/hooks/**", // Exclude shared hooks
    "src/shared/data/**" // Exclude data files
  ]
}

Key Explanations for the Config File:

Handling Dynamic Backend Error Codes

Overview

In addition to static error keys, the Next-i18n-auth system also needs to handle dynamic error codes that come from the backend (e.g., API responses). These dynamic error codes will be automatically parsed by i18next-scanner and added to the translation files, ensuring that all error messages are localized and available for internationalization.

Process for Handling Backend Error Codes

  1. Adding Dynamic Error Codes to the List:

Example:


export async function dummyTranslationsForScanner(
        t: TFunction<"shared.services.api">,
) {
  // Static error keys to be translated automatically by i18next-scanner
  // These are predefined error codes, and i18next-scanner will automatically generate their translations
  // Make sure to add dynamic backend-specific error codes here manually (as they are context-dependent).
  // After adding new error codes, run the `smart-i18n` task to update translations.
  return [
    // Axios-specific codes
    t("ERR_FR_TOO_MANY_REDIRECTS"),
    t("ERR_BAD_OPTION_VALUE"),
    t("ERR_BAD_OPTION"),
    t("ERR_NETWORK"),
    t("ERR_DEPRECATED"),
    t("ERR_BAD_RESPONSE"),
    t("ERR_BAD_REQUEST"),
    t("ERR_NOT_SUPPORT"),
    t("ERR_INVALID_URL"),
    t("ERR_CANCELED"),

    // Node.js low-level network errors
    t("ECONNREFUSED"),
    t("ECONNRESET"),
    t("ETIMEDOUT"),
    t("EHOSTUNREACH"),
    t("ENETUNREACH"),
    t("EAI_AGAIN"),
    t("ENOTFOUND"),
    t("EPIPE"),
    t("EACCES"),
    t("ECONNABORTED"),
  ];
}
  1. Run smart-i18n generate-templates:
  1. Manual Translation:
  1. Retain Unused Keys with keepUnusedKeys:

Example configuration snippet:

   {
     "keepUnusedKeys": true
   }

Why This Approach Works

For detailed principles behind translation key structure, see Translation Keys and Organization.

📚 Related Projects

This site is open source. Improve this page.