@plop-next/i18n 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @plop-next/i18n
+
+## 0.1.0
+
+### Minor Changes
+
+- "@plop-next/cli": minor
+
+  "@plop-next/core": minor
+
+  "@plop-next/i18n": minor
+
+  Refactor internal generator prompt handling from generator-select to generatorList across cli, core, and i18n.
+
+  Reserve generatorList for internal generator selection and improve validation and error messages.
+
+  Align theme selector flow and generated scaffold theme slots with generatorList.
+
+  Update i18n/theme integrations and tests to keep behavior consistent.
+
+### Patch Changes
+
+- Updated dependencies
+  - @plop-next/core@0.1.0

package/README.md

@@ -0,0 +1 @@
+# i18n

package/dist/index.d.ts

@@ -0,0 +1,341 @@
+import { PlopNextCore, LocaleTag, LocaleTexts, HelpTexts } from '@plop-next/core';
+
+type LocalesBundle = Record<string, LocaleTexts>;
+type LocaleSource = LocaleTexts | LocalesBundle | string;
+interface RegisterLocaleOptions {
+    /** If true, this locale becomes the active locale immediately. */
+    activate?: boolean;
+}
+/**
+ * PlopNextI18n
+ *
+ * Plugin class for `@plop-next/i18n`.
+ * Must be installed on a `PlopNextCore` instance before `useI18n` is called.
+ *
+ * @example
+ * import { PlopNextI18n } from "@plop-next/i18n";
+ * const i18nPlugin = new PlopNextI18n(plopNext);
+ * i18nPlugin.registerLocale("fr", frMessages);
+ * plopNext.useI18n({ force: "fr" });
+ */
+declare class PlopNextI18n {
+    private readonly core;
+    private readonly registry;
+    private enabled;
+    private readonly translatableRules;
+    constructor(core: PlopNextCore);
+    install(): this;
+    /**
+     * Register (or extend) a locale's message map.
+     * Merges deeply with any previously registered messages for that locale.
+     *
+     * @param locale   BCP-47 tag, e.g. "fr", "es", "ja"
+     * @param messages Flat or nested translation map
+     * @param options  `activate: true` sets this locale as active immediately
+     */
+    registerLocale(locale: LocaleTag, texts: LocaleTexts | string, options?: RegisterLocaleOptions): this;
+    registerLocales(locales: LocaleSource, options?: RegisterLocaleOptions): this;
+    /**
+     * Add or override texts for a locale. Merges deeply with existing texts.
+     *
+     * @param locale  Locale tag, e.g. "fr"
+     * @param texts   Partial or full nested text map
+     */
+    registerTexts(locale: LocaleTag, texts: LocaleTexts | string): this;
+    registerTexts(localesOrTexts: LocaleSource): this;
+    /**
+     * Override a single text value identified by a dot-notation path.
+     *
+     * @param locale  Locale tag, e.g. "fr"
+     * @param path    Dot-notation key, e.g. "cli.selectGenerator"
+     * @param text    The translated string or function
+     *
+     * @example
+     * i18n.registerText("fr", "cli.selectGenerator", "Choisissez un générateur");
+     */
+    registerText(locale: LocaleTag, path: string, text: unknown): this;
+    /**
+     * Return the currently active locale tag.
+     */
+    getActiveLocale(): LocaleTag;
+    /**
+     * Check if a locale has been registered.
+     */
+    hasLocale(locale: LocaleTag): boolean;
+    private resolveSingleLocaleTexts;
+    private resolveLocalesOrSingle;
+    private resolveFromPath;
+    private resolveScopedDirectory;
+    private parseScopedSourceFile;
+    private extractScopedObject;
+    private findLocaleExportKey;
+    private normalizeLocaleTag;
+    private resolveWelcomeMessageForLocale;
+    private emitI18nSourceWarning;
+    private parseSourceFile;
+    private parseJsonFile;
+    private parseModuleFile;
+    private normalizeObjectInput;
+    private isLocalesBundle;
+    private isLocaleLikeKey;
+    private looksLikeThemeObject;
+    private isPlainObject;
+    private unwrapModuleDefault;
+    private mergePlainObjects;
+    private normalize;
+    private enable;
+    private applyInquirerLocale;
+    private buildInquirerLocale;
+    private detectLocale;
+    private preparePrompts;
+    /**
+     * Resolve a prompt field translation with fallback chain:
+     * 1. Try with prompt name as-is (handles both plain names and indexed names like "name[0]")
+     * 2. If that doesn't resolve, try without any index suffix (for indexed arrays)
+     * 3. Fall back to provided default
+     *
+     * @example
+     * // For promptName="name[0]" and field="message":
+     * // Tries: "component.name[0].message" → "component.name.message" → fallback
+     */
+    private resolvePromptField;
+    private translateChoices;
+    private choiceKey;
+    /**
+     * Apply one translation rule to the (shallow-copied) prompt record.
+     *
+     * The implementation is purely functional: nested arrays / objects are
+     * reconstructed copy-on-write, so the original prompt config is never
+     * mutated.
+     */
+    private applyRule;
+    /**
+     * Recursively walk `segments` starting at `idx`, navigating into `current`.
+     * Returns a *new* value when a translation changed something, or `current`
+     * unchanged when nothing was modified (enabling cheap reference equality
+     * checks at every level).
+     */
+    private walkPath;
+    /**
+     * Translate `fieldName` on `obj`. Returns a *new* object when the translation
+     * differs from the original value, or `obj` itself when nothing changed.
+     */
+    private translateFieldValue;
+}
+
+declare class I18nRegistry {
+    private readonly locales;
+    private activeLocale;
+    constructor();
+    registerTexts(locale: LocaleTag, texts: LocaleTexts): void;
+    registerText(locale: LocaleTag, path: string, text: unknown): void;
+    registerLocale(locale: LocaleTag, texts: LocaleTexts): void;
+    setActiveLocale(locale: LocaleTag): void;
+    getActiveLocale(): LocaleTag;
+    hasLocale(locale: LocaleTag): boolean;
+    getLocaleValue(locale: LocaleTag, key: string): unknown;
+    t(key: string, args?: unknown[], defaultMessage?: string | ((...a: unknown[]) => string)): string;
+    private findValue;
+    /**
+     * Returns the `help` texts for the given locale, walking up parent locales
+     * (e.g. "fr-BE" → "fr" → "en") until a `help` section is found.
+     * Always returns at least the English default help texts.
+     */
+    getHelpTexts(locale: LocaleTag): HelpTexts;
+    /**
+     * Resolves help texts from the closest parent locale of `locale`.
+     * Returns `undefined` if no parent locale has help texts.
+     */
+    private resolveParentHelpTexts;
+    /**
+     * Returns an ordered list of candidate locales to try for `locale`.
+     * E.g. "fr-BE" → ["fr-BE", "fr", "en"]
+     */
+    private parentLocaleChain;
+    private deepMerge;
+}
+
+/**
+ * i18n-facing export of core-owned default English texts.
+ * Keep this alias for backward compatibility.
+ */
+declare const EN_MESSAGES: LocaleTexts;
+declare const BASE_LOCALE: LocaleTag;
+/**
+ * Preferred explicit naming for consumers wanting the default text bundle.
+ */
+declare const DEFAULT_TEXTS_EN: LocaleTexts;
+
+/**
+ * Spanish translations for plop-next built-in messages.
+ * Covers the same key structure as `@plop-next/core` English messages.
+ */
+declare const ES_MESSAGES: LocaleTexts;
+
+/**
+ * French translations for plop-next built-in messages.
+ * Covers the same key structure as `@plop-next/core` English messages.
+ */
+declare const FR_MESSAGES: LocaleTexts;
+
+/**
+ * Portuguese translations for plop-next built-in messages.
+ * Covers the same key structure as `@plop-next/core` English messages.
+ */
+declare const PT_MESSAGES: LocaleTexts;
+
+/**
+ * Chinese translations for plop-next built-in messages.
+ * Covers the same key structure as `@plop-next/core` English messages.
+ */
+declare const ZH_MESSAGES: LocaleTexts;
+
+/**
+ * Texts for a single prompt field (indexed or not).
+ *
+ * @example
+ * {
+ *   message: "What is your name?",
+ *   hint: "(required)",
+ *   description: "Your full name",
+ *   validate: "Name is required",
+ * }
+ */
+interface PromptFieldTexts {
+    message?: string;
+    hint?: string;
+    description?: string;
+    validate?: string;
+    instructions?: string;
+    helpText?: string;
+    noResults?: string;
+    searchingText?: string;
+    choices?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * Texts for a generator with multiple prompts.
+ * Structure: promptName -> { message, hint, description, choices, ... }
+ * For arrays of prompts, use numeric indices: name[0], name[1], etc.
+ *
+ * @example
+ * {
+ *   description: "Create a new component",
+ *   mode: {
+ *     message: "Quel mode ?",
+ *     choices: { add: "Ajouter", remove: "Supprimer" }
+ *   },
+ *   name: {
+ *     // For indexed prompts
+ *     "[0]": { message: "First component name" },
+ *     "[1]": { message: "Second component name" }
+ *   }
+ * }
+ */
+interface GeneratorTexts extends Record<string, unknown> {
+    description?: string;
+    [promptName: string]: PromptFieldTexts | string | unknown;
+}
+/**
+ * Texts for CLI interface (select generator, no generators, etc.)
+ *
+ * @example
+ * {
+ *   welcome: "Welcome to plop-next!",
+ *   selectGenerator: "Please choose a generator",
+ *   noGenerators: "No generators registered",
+ *   aborted: "Operation cancelled",
+ *   done: "Done!",
+ * }
+ */
+interface CliTexts {
+    welcome?: string;
+    welcomeMessage?: string | null;
+    selectGenerator?: string;
+    noGenerators?: string;
+    generatorNotFound?: string | ((...args: unknown[]) => string);
+    aborted?: string;
+    done?: string;
+}
+/**
+ * @inquirer/prompts locale configuration.
+ * These control UI elements like confirm (Yes/No), select help text, etc.
+ *
+ * @example
+ * {
+ *   confirm: {
+ *     yesLabel: "Yes",
+ *     noLabel: "No",
+ *     hintYes: "Y/n",
+ *     hintNo: "y/N",
+ *   },
+ *   select: {
+ *     helpNavigate: "navigate",
+ *     helpSelect: "select",
+ *   },
+ * }
+ */
+interface InquirerTexts {
+    confirm?: {
+        yesLabel?: string;
+        noLabel?: string;
+        hintYes?: string;
+        hintNo?: string;
+    };
+    select?: {
+        helpNavigate?: string;
+        helpSelect?: string;
+    };
+    checkbox?: {
+        helpNavigate?: string;
+        helpSelect?: string;
+        helpSubmit?: string;
+        helpAll?: string;
+        helpInvert?: string;
+    };
+    search?: {
+        helpNavigate?: string;
+        helpSelect?: string;
+    };
+    expand?: Record<string, unknown>;
+    rawlist?: Record<string, unknown>;
+    editor?: {
+        waitingMessage?: string | ((enterKey: string) => string);
+    };
+    input?: Record<string, unknown>;
+    number?: Record<string, unknown>;
+    password?: {
+        maskedText?: string;
+    };
+}
+/**
+ * Complete i18n text bundle for a locale.
+ * Includes CLI texts, generator-specific texts, and @inquirer/prompts texts.
+ *
+ * @example
+ * {
+ *   cli: { ... },
+ *   inquirer: { ... },
+ *   component: { description: "...", name: { ... } },
+ *   myGenerator: { ... },
+ * }
+ */
+interface LocalizedTextsBundle extends LocaleTexts {
+    cli?: CliTexts;
+    inquirer?: InquirerTexts;
+    [generatorName: string]: unknown;
+}
+/**
+ * Helper type to define all texts for a locale in a type-safe manner.
+ * Use as const to ensure proper typing:
+ *
+ * @example
+ * const frTexts: LocaleTextsDef = {
+ *   cli: { selectGenerator: "Choisir un générateur" },
+ *   inquirer: { confirm: { yesLabel: "Oui" } },
+ *   component: { description: "Créer un composant" },
+ * } as const;
+ */
+type LocaleTextsDef = LocalizedTextsBundle;
+
+export { BASE_LOCALE, type CliTexts, DEFAULT_TEXTS_EN, EN_MESSAGES, ES_MESSAGES, FR_MESSAGES, type GeneratorTexts, I18nRegistry, type InquirerTexts, type LocaleTextsDef, type LocalizedTextsBundle, PT_MESSAGES, PlopNextI18n, type PromptFieldTexts, type RegisterLocaleOptions, ZH_MESSAGES };