@next-vibe/checker 1.0.11

package/src/i18n/core/scoped-translation.ts

@@ -0,0 +1,120 @@
+/**
+ * Scoped Translation Factory
+ * Creates module-specific translation functions that work only within a defined scope
+ */
+
+import { type CountryLanguage, defaultLocale, type Languages } from "./config";
+import { getLanguageFromLocale } from "./language-utils";
+import {
+  navigateTranslationObject,
+  processTranslationValue,
+} from "./shared-translation-utils";
+import type { TParams } from "./static-types";
+import type { DotNotation } from "./static-types";
+
+// this value should never be used at runtime
+export type TranslatedKeyType = "createScopedTranslation-key";
+
+/**
+ * Translation schema type for scoped modules
+ * Supports deeply nested structures with recursive type definition
+ */
+export interface ScopedTranslationSchema {
+  [key: string]: string | ScopedTranslationSchema;
+}
+
+/**
+ * Creates a scoped translation system for a specific module
+ * EN translations are used as the source of truth for type safety
+ *
+ * @param translationsByLanguage - Object mapping language codes to their translation schemas
+ * @returns A simpleT function that works only with the provided translations
+ *
+ * @example
+ * // In src/app/api/[locale]/sms/i18n/index.ts
+ * import { createScopedTranslation } from "@/i18n/core/scoped-translation";
+ * import { translations as enTranslations } from "./en";
+ * import { translations as deTranslations } from "./de";
+ * import { translations as plTranslations } from "./pl";
+ *
+ * export const simpleT = createScopedTranslation({
+ *   en: enTranslations,
+ *   de: deTranslations,
+ *   pl: plTranslations,
+ * });
+ *
+ * // Usage:
+ * const { t } = simpleT("en-GLOBAL");
+ * t("sms.error.invalid_phone_format"); // Type-safe based on EN schema
+ */
+/**
+ * Helper type to extract the scoped translation key type from createScopedTranslation return
+ */
+export type ExtractScopedTranslationKey<T> = T extends {
+  ScopedTranslationKey: infer K;
+}
+  ? K
+  : never;
+
+export function createScopedTranslation<
+  const TTranslations extends Record<Languages, ScopedTranslationSchema>,
+>(
+  translationsByLanguage: TTranslations,
+): {
+  readonly ScopedTranslationKey: DotNotation<TTranslations["en"]>;
+  readonly scopedT: (locale: CountryLanguage) => {
+    t: (
+      key: DotNotation<TTranslations["en"]>,
+      params?: TParams,
+    ) => TranslatedKeyType;
+  };
+} {
+  return {
+    ScopedTranslationKey: undefined as DotNotation<TTranslations["en"]>,
+
+    scopedT: function simpleT(locale: CountryLanguage): {
+      t: (
+        key: DotNotation<TTranslations["en"]>,
+        params?: TParams,
+      ) => TranslatedKeyType;
+    } {
+      return {
+        t: (
+          key: DotNotation<TTranslations["en"]>,
+          params?: TParams,
+        ): TranslatedKeyType => {
+          // Extract language from locale with safety check
+          if (!locale || typeof locale !== "string") {
+            return key as TranslatedKeyType; // Return the key as fallback
+          }
+          if (!key || typeof key !== "string") {
+            return key as TranslatedKeyType; // Return the key as fallback
+          }
+
+          const language = locale.split("-")[0] as Languages;
+          const defaultLanguage = getLanguageFromLocale(defaultLocale);
+
+          // Get translations for the requested language
+          const languageTranslations = translationsByLanguage[language];
+          const fallbackTranslations = translationsByLanguage[defaultLanguage];
+
+          // Navigate through the translation object using shared logic
+          const keys = (key as string).split(".");
+          let value = navigateTranslationObject(languageTranslations, keys);
+
+          // Try fallback language if value not found
+          if (value === undefined && language !== defaultLanguage) {
+            value = navigateTranslationObject(fallbackTranslations, keys);
+          }
+
+          // Process the translation value using shared logic (handles parameter replacement)
+          return processTranslationValue(
+            value,
+            key,
+            params as TParams,
+          ) as TranslatedKeyType;
+        },
+      };
+    },
+  };
+}

package/src/i18n/core/shared-component.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+
+import type { CountryLanguage } from "./config";
+import { _simpleT } from "./shared";
+import type { TranslationKey, TranslationValue } from "./static-types";
+import { renderTranslation } from "./translation-utils";
+
+interface SimpleTranslationProps<K extends TranslationKey> {
+  lang: CountryLanguage;
+  i18nKey: K;
+  values?: TranslationValue<K> extends string
+    ? Record<string, string | number>
+    : never;
+}
+
+/**
+ * Server-side translation component
+ * Use this for translations in server components
+ */
+export default function SimpleT<K extends TranslationKey>({
+  lang,
+  i18nKey,
+  values,
+}: SimpleTranslationProps<K>): ReactNode {
+  // Use simpleT directly which already uses the shared utility
+  const translatedValue = _simpleT(lang, i18nKey, values);
+
+  // Use the shared rendering logic
+  return renderTranslation(translatedValue, i18nKey);
+}

package/src/i18n/core/shared-translation-utils.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared Translation Utilities
+ * Core logic for navigating translation objects and processing values
+ * Used by both global and scoped translation systems
+ */
+
+import { translationsKeyMode } from "@/config/debug";
+
+import type { TParams } from "./static-types";
+
+/**
+ * Nested translation value type supporting deep nesting
+ */
+export type NestedValue = string | { [key: string]: NestedValue };
+
+/**
+ * Navigate through a translation object using an array of keys
+ * This is the core navigation logic shared between global and scoped translations
+ */
+export function navigateTranslationObject(
+  startValue: Record<string, NestedValue>,
+  keys: string[],
+): NestedValue | undefined {
+  let value: NestedValue | undefined = startValue as NestedValue;
+
+  for (const k of keys) {
+    if (value === undefined || value === null) {
+      break;
+    }
+
+    // Handle array access
+    if (Array.isArray(value)) {
+      const index = Number(k);
+      if (!Number.isNaN(index) && index >= 0 && index < value.length) {
+        value = value[index] as NestedValue;
+      } else {
+        value = undefined;
+        break;
+      }
+    }
+    // Handle object access
+    else if (typeof value === "object" && k in value) {
+      value = (value as Record<string, NestedValue>)[k];
+    } else {
+      value = undefined;
+      break;
+    }
+  }
+
+  return value;
+}
+
+/**
+ * Process translation value and handle parameters
+ * Shared logic for parameter replacement in translation strings
+ */
+export function processTranslationValue<K extends string>(
+  value: NestedValue | undefined,
+  key: K,
+  params?: TParams,
+): string {
+  // If value is undefined, return the key as fallback
+  if (value === undefined || value === null) {
+    return `${key}${params ? ` (${JSON.stringify(params)})` : ""}`;
+  }
+
+  // If value is a string, process parameters
+  if (typeof value === "string") {
+    let translationValue: string = value;
+    if (params) {
+      Object.entries(params).forEach(([paramKey, paramValue]) => {
+        translationValue = translationValue.replaceAll(
+          new RegExp(`{{${paramKey}}}`, "g"),
+          String(paramValue),
+        );
+      });
+    }
+
+    // Handle translation key mode for debugging
+    if (translationsKeyMode) {
+      // Return URLs (remote and local) as-is
+      if (
+        translationValue.startsWith("http://") ||
+        translationValue.startsWith("/") ||
+        translationValue.startsWith("https://")
+      ) {
+        return translationValue;
+      }
+
+      return params ? `${key} (${Object.keys(params).join(", ")})` : `${key}`;
+    }
+    return translationValue;
+  }
+
+  // Handle non-string values - return the key as fallback
+  return key;
+}

package/src/i18n/core/shared.ts

@@ -0,0 +1,44 @@
+import type { CountryLanguage, Languages } from "./config";
+import type { TFunction, TParams, TranslationKey } from "./static-types";
+import { translateKey } from "./translation-utils";
+
+// Server-side translation function
+export function simpleT(locale: CountryLanguage): {
+  t: TFunction;
+} {
+  return {
+    t: <K extends TranslationKey>(key: K, params?: TParams): string => {
+      return _simpleT(locale, key, params);
+    },
+  };
+}
+
+// Server-side translation function
+export function _simpleT<K extends TranslationKey>(
+  locale: CountryLanguage,
+  key: K,
+  params?: TParams,
+): string {
+  // Extract language from locale with safety check
+  if (!locale || typeof locale !== "string") {
+    // oxlint-disable-next-line no-console
+    console.error("Invalid locale provided to translation function:", locale);
+    return key; // Return the key as fallback
+  }
+  if (!key || typeof key !== "string") {
+    // oxlint-disable-next-line no-console
+    console.error("Invalid key provided to translation function:", key);
+    return key; // Return the key as fallback
+  }
+
+  const language = locale.split("-")[0] as Languages;
+
+  // Use the shared translation utility with server context
+  return translateKey(
+    key,
+    language,
+    params,
+    undefined, // Use default fallback language
+    "server",
+  );
+}

package/src/i18n/core/static-types.ts

@@ -0,0 +1,72 @@
+import type { ExplicitObjectType } from "next-vibe/shared/types/utils";
+
+import type { translationsKeyTypesafety } from "@/config/debug";
+
+import type { TranslationSchema } from "./config";
+import type { TranslatedKeyType } from "./scoped-translation";
+
+export interface TranslationElement {
+  [key: string]: string | number | string[] | TranslationElement;
+}
+
+// Utility type to create dot-notation paths for nested objects
+type DotPrefix<T extends string> = T extends "" ? "" : `.${T}`;
+
+export type DotNotation<T> = (
+  T extends ExplicitObjectType
+    ? {
+        [K in Exclude<keyof T, symbol>]: `${K}${DotPrefix<DotNotation<T[K]>>}`;
+      }[Exclude<keyof T, symbol>]
+    : ""
+) extends infer D
+  ? Extract<D, string>
+  : never;
+
+// Type for all possible translation keys
+export type TranslationKey = typeof translationsKeyTypesafety extends true
+  ? _TranslationKey
+  : string;
+export type _TranslationKey =
+  | DotNotation<TranslationSchema>
+  | TranslatedKeyType;
+
+// Utility type to get the type of a value at a specific path
+type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}`
+  ? K extends keyof T
+    ? PathValue<T[K], Rest>
+    : never
+  : P extends keyof T
+    ? T[P]
+    : never;
+
+// Type for getting the value type of a translation key
+export type TranslationValue<K extends TranslationKey> = PathValue<
+  TranslationSchema,
+  K
+>;
+
+export type TParams = Record<string, string | number>;
+export type TFunction = <K extends TranslationKey>(
+  key: K,
+  params?: TParams,
+) => string;
+
+/**
+ * Utility type to extract the scoped key type from a scopedT function or scoped translation object
+ *
+ * For best results, use with the full createScopedTranslation result which includes ScopedTranslationKey:
+ * @example
+ * import { scopedTranslation } from "@/app/api/[locale]/contact/i18n";
+ * type ContactKeys = ExtractScopedKeyType<typeof scopedTranslation>;
+ * // ContactKeys = "title" | "description" | "form.label" | "form.fields.name.label" | ...
+ *
+ * For scopedT functions, use the string type from the scoped translation object's ScopedTranslationKey:
+ * @example
+ * type ContactKeys = typeof scopedTranslation.ScopedTranslationKey;
+ */
+export type ExtractScopedKeyType<T> =
+  // If T has ScopedTranslationKey property (from createScopedTranslation result), extract it
+  T extends { ScopedTranslationKey: infer K extends string }
+    ? K
+    : // Otherwise return never - use the ScopedTranslationKey property directly instead
+      never;

package/src/i18n/core/translation-utils.ts

@@ -0,0 +1,218 @@
+import { Environment } from "next-vibe/shared/utils";
+import type { ReactNode } from "react";
+
+import { envClient } from "@/config/env-client";
+
+import { languageConfig } from "..";
+import type { Countries, CountryLanguage, Languages } from "./config";
+import { defaultLocaleConfig, translations } from "./config";
+import type {
+  TParams,
+  TranslationElement,
+  TranslationKey,
+} from "./static-types";
+
+// ================================================================================
+// TRANSLATION UTILITIES
+// ================================================================================
+
+/**
+ * Centralized translation error handling
+ * This ensures we only log each error once and in a consistent format
+ */
+export function logTranslationError(
+  errorType: "missing" | "invalid_type" | "fallback_missing",
+  key: string,
+  context?: string,
+): void {
+  if (!languageConfig.debug || envClient.NODE_ENV === Environment.PRODUCTION) {
+    return;
+  }
+
+  const prefix = context ? `[${context}] ` : "";
+
+  // Using process.stderr for error logging in development
+  // In production, these would be caught by error monitoring
+  switch (errorType) {
+    case "missing":
+      if (typeof process !== "undefined" && process.stderr) {
+        process.stderr.write(`${prefix}Translation key not found: ${key}\n`);
+      }
+      break;
+    case "invalid_type":
+      if (typeof process !== "undefined" && process.stderr) {
+        process.stderr.write(
+          `${prefix}Translation key "${key}" has invalid type (expected string)\n`,
+        );
+      }
+      break;
+    case "fallback_missing":
+      if (typeof process !== "undefined" && process.stderr) {
+        process.stderr.write(
+          `${prefix}Translation key not found in fallback language: ${key}\n`,
+        );
+      }
+      break;
+  }
+}
+
+/**
+ * Navigate through a translation object using an array of keys
+ */
+function navigateTranslationPath(
+  startValue: TranslationElement,
+  keys: string[],
+  fullKey: string,
+  language: Languages,
+  fallbackLanguage: Languages,
+  isUsingFallback: boolean,
+  context?: string,
+): TranslationElement | string | undefined {
+  // Import shared navigation logic
+  const { navigateTranslationObject } = require("./shared-translation-utils");
+  const value = navigateTranslationObject(startValue, keys);
+
+  // Handle error logging for missing keys
+  if (
+    value === undefined &&
+    (isUsingFallback || language === fallbackLanguage)
+  ) {
+    logTranslationError(
+      isUsingFallback ? "fallback_missing" : "missing",
+      fullKey,
+      context,
+    );
+  }
+
+  return value as TranslationElement | string | undefined;
+}
+
+/**
+ * Try to get translation from a specific language
+ */
+function tryGetTranslation<K extends TranslationKey>(
+  key: K,
+  language: Languages,
+  isUsingFallback: boolean,
+  fallbackLanguage: Languages,
+  context?: string,
+): TranslationElement | string | undefined {
+  const keys = key?.split(".");
+  const translationsForLanguage = translations[language];
+
+  if (!translationsForLanguage) {
+    return undefined;
+  }
+
+  return navigateTranslationPath(
+    translationsForLanguage,
+    keys,
+    key,
+    language,
+    fallbackLanguage,
+    isUsingFallback,
+    context,
+  );
+}
+
+/**
+ * Get translation value from nested object using dot notation
+ */
+export function getTranslationValue<K extends TranslationKey>(
+  key: K,
+  language: Languages,
+  fallbackLanguage: Languages = defaultLocaleConfig.language,
+  context?: string,
+): TranslationElement | string | undefined {
+  // Try with the specified language first
+  const value = tryGetTranslation(
+    key,
+    language,
+    false,
+    fallbackLanguage,
+    context,
+  );
+
+  // If translation not found and not already using fallback, try fallback language
+  if (value === undefined && language !== fallbackLanguage) {
+    return tryGetTranslation(
+      key,
+      fallbackLanguage,
+      true,
+      fallbackLanguage,
+      context,
+    );
+  }
+
+  return value;
+}
+
+/**
+ * Process translation value and handle parameters
+ */
+export function processTranslationValue<K extends TranslationKey>(
+  value: TranslationElement | string | undefined,
+  key: K,
+  params?: TParams,
+  context?: string,
+): string {
+  // Import shared processing logic
+  const {
+    processTranslationValue: sharedProcess,
+  } = require("./shared-translation-utils");
+  const result = sharedProcess(value, key, params, context);
+
+  // Log error if value was not a string (only for global translations)
+  if (value !== undefined && value !== null && typeof value !== "string") {
+    logTranslationError("invalid_type", key, context);
+  }
+
+  return result;
+}
+
+/**
+ * Main translation function that combines getting and processing the value
+ */
+export function translateKey<K extends TranslationKey>(
+  key: K,
+  language: Languages,
+  params?: TParams,
+  fallbackLanguage?: Languages,
+  context?: string,
+): string {
+  // Use hardcoded fallback to avoid circular dependency during initialization
+  const actualFallbackLanguage = fallbackLanguage ?? "en";
+  const value = getTranslationValue(
+    key,
+    language,
+    actualFallbackLanguage,
+    context,
+  );
+  return processTranslationValue(value, key, params, context);
+}
+
+/**
+ * Shared component rendering logic for translation components
+ * This can be used by both client and server components
+ */
+export function renderTranslation<K extends TranslationKey>(
+  translatedValue: string | undefined,
+  key: K,
+): ReactNode {
+  // If the translation is empty or not a string, show the key as fallback
+  if (!translatedValue) {
+    // We don't log here because the error would have already been logged
+    // in getTranslationValue or processTranslationValue
+    return key;
+  }
+
+  return translatedValue;
+}
+
+export function getCountryFromLocale(locale: CountryLanguage): Countries {
+  return locale.split("-")[1] as Countries;
+}
+
+export function getLanguageFromLocale(locale: CountryLanguage): Languages {
+  return locale.split("-")[0] as Languages;
+}

package/src/i18n/de/index.ts

@@ -0,0 +1,8 @@
+import { translations as apiTranslations } from "../../app/i18n/de";
+import { translations as configTranslations } from "../../config/i18n/de";
+import type { translations as enTranslations } from "../en";
+
+export const translations: typeof enTranslations = {
+  app: apiTranslations,
+  config: configTranslations,
+};

package/src/i18n/en/index.ts

@@ -0,0 +1,7 @@
+import { translations as apiTranslations } from "../../app/i18n/en";
+import { translations as configTranslations } from "../../config/i18n/en";
+
+export const translations = {
+  app: apiTranslations,
+  config: configTranslations,
+};

package/src/i18n/index.ts

@@ -0,0 +1,100 @@
+import type { LanguageConfig, LanguageDefaults } from "./core/config";
+import { translations as deTranslations } from "./de";
+import { translations as enTranslations } from "./en";
+import { translations as plTranslations } from "./pl";
+
+// ----------------
+// CONFIGURATION
+// ----------------
+export const languageDefaults = {
+  country: "GLOBAL" as const,
+  currency: "USD",
+  language: "en" as const,
+  translations: enTranslations,
+} satisfies LanguageDefaults<typeof enTranslations>;
+
+export const allTranslations = {
+  de: deTranslations,
+  pl: plTranslations,
+  en: enTranslations,
+};
+
+export const languageConfig = {
+  debug: false as boolean,
+  countries: {
+    DE: "DE" as const,
+    PL: "PL" as const,
+    US: "US" as const,
+    GLOBAL: "GLOBAL" as const,
+  },
+  countriesArr: ["DE", "PL", "US", "GLOBAL"] as const,
+
+  currencies: {
+    EUR: "EUR" as const,
+    USD: "USD" as const,
+    PLN: "PLN" as const,
+  },
+  currenciesArr: ["EUR", "USD", "PLN"] as const,
+
+  languages: {
+    DE: "de" as const,
+    PL: "pl" as const,
+    EN: "en" as const,
+  },
+  languagesArr: ["de", "pl", "en"] as const,
+
+  mappings: {
+    currencyByCountry: {
+      DE: "EUR",
+      PL: "PLN",
+      US: "USD",
+      GLOBAL: "USD",
+    },
+
+    languageByCountry: {
+      DE: "de",
+      PL: "pl",
+      US: "en",
+      GLOBAL: "en",
+    },
+  },
+
+  countryInfo: {
+    DE: {
+      code: "DE",
+      name: "Deutschland",
+      language: "de",
+      langName: "Deutsch",
+      flag: "🇩🇪",
+      currency: "EUR",
+      symbol: "€",
+    },
+    PL: {
+      code: "PL",
+      name: "Polska",
+      language: "pl",
+      langName: "Polski",
+      flag: "🇵🇱",
+      currency: "PLN",
+      symbol: "zł",
+    },
+    US: {
+      code: "US",
+      name: "United States",
+      language: "en",
+      langName: "English",
+      flag: "🇺🇸",
+      currency: "USD",
+      symbol: "$",
+    },
+    GLOBAL: {
+      code: "GLOBAL",
+      name: "Global",
+      language: "en",
+      langName: "English",
+      flag: "🌐",
+      currency: "USD",
+      symbol: "$",
+    },
+  },
+} satisfies LanguageConfig;