@iamalond/nestjs-i18next 1.3.0 → 1.3.1

package/README.md

@@ -10,7 +10,7 @@
     <a href='https://img.shields.io/npm/v/@iamalond/nestjs-i18next'><img src="https://img.shields.io/npm/v/@iamalond/nestjs-i18next" alt="NPM Version" /></a>
     <a href='https://img.shields.io/npm/l/@iamalond/nestjs-i18next'><img src="https://img.shields.io/npm/l/@iamalond/nestjs-i18next" alt="NPM License" /></a>
     <a href='https://img.shields.io/npm/dm/@iamalond/nestjs-i18next'><img src="https://img.shields.io/npm/dm/@iamalond/nestjs-i18next" alt="NPM Downloads" /></a>
-    <a href='https://img.shields.io/github/last-commit/iamalond/@iamalond/nestjs-i18next'><img src="https://img.shields.io/github/last-commit/iamalond/@iamalond/nestjs-i18next" alt="Last commit" /></a>
+    <a href='https://img.shields.io/github/last-commit/iamAlond/nestjs-i18next'><img src="https://img.shields.io/github/last-commit/iamAlond/nestjs-i18next" alt="Last commit" /></a>
 </p>
 
 ## About the Project
@@ -30,16 +30,20 @@ The project was inspired by the popular `nestjs-i18n` module, but with a major e
 
 ## Installation
 
+**Node.js 18.0.0 or newer is required.**
+
 ```bash
-npm install nestjs-i18next
-yarn add nestjs-i18next
-pnpm add nestjs-i18next
+$ npm install @iamalond/nestjs-i18next
+$ yarn add @iamalond/nestjs-i18next
+$ pnpm add @iamalond/nestjs-i18next
 ```
 
 ## Usage
 
+After installation, we can import the `I18nextModule` into the root `AppModule`:
+
 ```typescript
-import { I18NextModule } from '@iamalond/nestjs-i18next';
+import { I18nextModule } from '@iamalond/nestjs-i18next';
 
 @Module({
     imports: [
@@ -59,14 +63,115 @@ import { I18NextModule } from '@iamalond/nestjs-i18next';
 export class AppModule {}
 ```
 
+Then use `I18nextService` in your service's constructor:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { I18nextService } from '@iamalond/nestjs-i18next';
+/**
+ * Import the types from the path you specified in 'generatedTypesPath'
+ * (e.g., src/i18n/index.d.ts)
+ */
+import { I18nTranslations } from './i18n';
+
+@Injectable()
+export class AppService {
+    // Pass I18nTranslations to the service for strict typing
+    constructor(private readonly i18n: I18nextService<I18nTranslations>) {}
+
+    getHello(): string {
+        // 1. Simple translation (autocomplete for keys, when start typing!)
+        const simple = this.i18n.t('common.hello');
+
+        // 2. Translation with arguments (Typescript will REQUIRE 'args' if variables exist)
+        const withArgs = this.i18n.t('common.welcome', {
+            args: { name: 'Matvey iamAlond' },
+            lang: 'en'
+        });
+
+        const apples = this.i18n.t('common.apples', {
+            args: { count: 5 }
+        });
+
+        // 3. You can also use the 'translate' alias
+        return this.i18n.translate('core.errors.notFound', {
+            defaultValue: 'Not Found',
+            debug: true
+        });
+    }
+}
+```
+
+### Dynamic Translation Keys
+
+If you need to use a dynamic key (e.g., based on an HTTP status code), use the I18nPath type. This type is also automatically generated in your generatedTypesPath and contains all valid translation paths.
+
+```typescript
+import { I18nPath, I18nTranslations } from './i18n';
+
+@Injectable()
+export class ErrorsService {
+    constructor(private readonly i18n: I18nextService<I18nTranslations>) {}
+
+    handleError(statusCode: number) {
+        /**
+         * Use 'as I18nPath' to tell TypeScript that this string
+         * is a valid translation key.
+         */
+        return this.i18n.t(`errors.status.${statusCode}` as I18nPath, {
+            defaultValue: 'An unexpected error occurred'
+        });
+    }
+}
+```
+
 ## File Structure
 
-By default, the module uses the locale/ns.json structure. With subfolders: true, you can use recursive nesting. Keys will be resolved as namespace.subfolder.key:
+By default, the module uses the locale/ns.json structure. With subfolders: true, you can use recursive nesting. Keys will be resolved as `namespace.subfolder.key`. You can also combine both of these approaches.
 
 ```bash
 src/i18n/
 ├── en/
 │   ├── common.json
-│   └── auth/
-│       └── errors.json  <-- key will be "auth.errors.invalid_password"
+│   └── core/
+│       └── errors.json  <-- key will be "core.errors.invalid_password"
+└── ru/
+    ├── common.json
+    └── ...
+```
+
+### Examples
+
+To support the examples above, your translation directory should look like this:
+
+`src/i18n/en/common.json`
+
+```json
+{
+    "hello": "Hello!",
+    "welcome": "Welcome, {{name}}!",
+    "apples": "{count, plural, =0 {No apples} one {# apple} =3 {three apples} other {# apples}}"
+}
 ```
+
+`src/i18n/en/core/errors.json`
+
+```json
+{
+    "invalid_password": "Invalid password",
+    "notFound": "Resource not found",
+    "status": {
+        "400": "Bad request",
+        "401": "Unauthorized",
+        "403": "Forbidden",
+        "404": "Not found",
+        "500": "Internal server error"
+    }
+}
+```
+
+## Key Resolution Rules
+
+- Simple file: common.json -> key starts with common (e.g., common.hello).
+- Subfolders: core/errors.json -> key starts with core.errors (e.g., core.errors.status.404).
+- Arguments: Any string containing {{var}} or ICU structures like {count, plural, ...} will automatically require args in your TypeScript code.

package/dist/nestjs-i18next.d.ts

@@ -9,16 +9,16 @@ export type I18nextModuleOptions = {
     throwOnMissingKey?: boolean;
     generatedTypesPath?: string;
 };
-export type TranslateOptions<P, T> = {
+type BaseOptions = {
     lang?: string;
     defaultValue?: string;
     debug?: boolean;
-} & (Extract<T, {
+};
+export type TranslateOptions<P, T> = Extract<T, {
     key: P;
 }> extends {
     args: infer A;
-} ? {
+} ? BaseOptions & {
     args: A;
-} : {
-    args?: never;
-});
+} : BaseOptions | undefined;
+export {};

package/dist/nestjs-i18next.json-loader.js

@@ -104,11 +104,6 @@ export type I18nTranslations = ${this.generateUnionType(schema)};
 
 /* prettier-ignore */
 export type I18nPath = I18nTranslations['key'];
-
-/* prettier-ignore */
-export type ExtractArgs<P extends I18nPath> = Extract<I18nTranslations, { key: P }> extends { args: infer A }
-    ? A
-    : never;
 `;
         fs_1.default.mkdirSync(path_1.default.dirname(outputPath), {
             recursive: true

package/dist/nestjs-i18next.service.d.ts

@@ -17,8 +17,16 @@ export declare class I18nextService<T extends {
     getSupportedLanguages(): string[];
     getTranslations(): Record<string, any>;
     getTranslationsForNamespace(lang: string): any;
-    translate<P extends T['key']>(key: P, options: TranslateOptions<P, T>): string;
-    t<P extends T['key']>(key: P, options: TranslateOptions<P, T>): string;
+    translate<P extends T['key']>(key: P, ...params: Extract<T, {
+        key: P;
+    }> extends {
+        args: any;
+    } ? [options: TranslateOptions<P, T>] : [options?: TranslateOptions<P, T>]): string;
+    t<P extends T['key']>(key: P, ...params: Extract<T, {
+        key: P;
+    }> extends {
+        args: any;
+    } ? [options: TranslateOptions<P, T>] : [options?: TranslateOptions<P, T>]): string;
     private getValueByKey;
     private replaceArgs;
     private handleMissingKey;

package/dist/nestjs-i18next.service.js

@@ -46,11 +46,11 @@ let I18nextService = I18nextService_1 = class I18nextService {
     getTranslationsForNamespace(lang) {
         return this.currentTranslations[lang];
     }
-    translate(key, options) {
-        return this.t(key, options);
+    translate(key, ...params) {
+        return this.t(key, ...params);
     }
-    t(key, options) {
-        const { lang, debug, defaultValue } = options || {};
+    t(key, ...params) {
+        const { lang, debug, defaultValue, ...options } = params[0] || {};
         const fallback = this.options.fallbackLanguage;
         let result = this.getValueByKey(key, lang ?? fallback);
         if (result === undefined && lang && lang !== fallback) {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@iamalond/nestjs-i18next",
 	"description": "🌍 i18next module for NestJS",
-	"version": "1.3.0",
+	"version": "1.3.1",
 	"scripts": {
 		"build": "rimraf -rf dist && tsc -p tsconfig.build.json",
 		"prepublish:npm": "npm run build",