chapterjs 0.1.4 → 0.2.0

package/dist/messages/declaration.js

@@ -0,0 +1,455 @@
+// What a file declares with `language()`: the texts of the bot in one
+// language. What a file declares is checked when it loads, and the
+// languages are checked against each other once loaded: every one has the
+// texts of the default language, with the same placeholders, so a missing
+// text is explained before anyone asks for it.
+import { readFile } from 'node:fs/promises';
+import { commandName } from '../commands/tree.js';
+import { listSources, siteName, } from '../loader/loader.js';
+import { isLanguageDeclaration } from './messages.js';
+import { FRAMEWORK, FRAMEWORK_KEYS } from './phrases.js';
+import { compile, compilePlural, LOCALES, PLURAL_FORMS, } from './translate.js';
+const fail = message => {
+    throw new TypeError(message);
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const KEYS = ['locale', 'default', 'texts', 'commands', 'framework'];
+const EXAMPLE = `language({ locale: 'en-US', texts: { pong: 'Pong!' } })`;
+/** Placeholders, for a message: `{name}, {count}`, or `none`. */
+const showParams = (names) => names.length === 0 ? 'none' : names.map(name => `{${name}}`).join(', ');
+/** Whether two templates take the same placeholders. */
+const samePlaceholders = (a, b) => [...a.params].sort().join('\0') === [...b.params].sort().join('\0');
+/** One form of a text, cut around its placeholders, each one checked. */
+function readForm(what, text, example) {
+    if (typeof text !== 'string' || text === '') {
+        fail(`${what} must be a text: ${example}`);
+    }
+    const template = compile(text);
+    for (const name of template.params) {
+        if (!NAME.test(name)) {
+            fail(`${what} has a placeholder "{${name}}": a placeholder is a name made of letters, digits and _, like {name}.`);
+        }
+    }
+    return template;
+}
+/**
+ * A text of a language file: a string, or a plural (one form per
+ * quantity, `other` at least), with an error saying what to write.
+ */
+function readText(key, text, kind = 'message') {
+    const what = `The ${kind} "${key}"`;
+    if (isRecord(text)) {
+        const forms = new Map();
+        for (const [form, one] of Object.entries(text)) {
+            if (!PLURAL_FORMS.includes(form)) {
+                fail(`"${form}" is not a form of the plural "${key}". A plural has: ${PLURAL_FORMS.join(', ')} (other at least): ${key}: { one: '{count} member', other: '{count} members' }`);
+            }
+            forms.set(form, readForm(`The form "${form}" of the plural "${key}"`, one, `${form}: '{count} members'`));
+        }
+        if (!forms.has('other')) {
+            fail(`The plural "${key}" needs an "other" form, used when no other form fits: ${key}: { one: '{count} member', other: '{count} members' }`);
+        }
+        return compilePlural(forms);
+    }
+    return readForm(what, text, `${key}: 'Hello {name}!'${kind === 'message' ? `, or a plural: ${key}: { one: '{count} member', other: '{count} members' }` : ''}`);
+}
+/** The language a declaration says it is, or an error saying which ones exist. */
+function readLocale(locale) {
+    if (locale === undefined) {
+        fail(`This language has no "locale": the language its texts are in, like ${EXAMPLE}. It can be: ${[...LOCALES].join(', ')}.`);
+    }
+    if (typeof locale !== 'string' || !LOCALES.has(locale)) {
+        fail(`${JSON.stringify(locale) ?? typeof locale} is not a language Discord knows. "locale" can be: ${[...LOCALES].join(', ')}.`);
+    }
+    return locale;
+}
+/**
+ * A language, declared anywhere in `src/` with `language()`: `locale` says
+ * which one, `texts` what the bot says in it.
+ */
+export const languageDeclaration = {
+    one: 'language',
+    many: 'languages',
+    is: isLanguageDeclaration,
+    list: true,
+    read(value) {
+        const config = value.config;
+        if (!isRecord(config)) {
+            return fail(`language() needs an object: ${EXAMPLE}`);
+        }
+        const locale = readLocale(config.locale);
+        for (const key of Object.keys(config)) {
+            if (!KEYS.includes(key)) {
+                fail(`"${key}" is not something a language has. It can have: ${KEYS.join(', ')}.`);
+            }
+        }
+        if (config.default !== undefined && typeof config.default !== 'boolean') {
+            fail(`"default" is true or false, got ${JSON.stringify(config.default)}.`);
+        }
+        if (!isRecord(config.texts)) {
+            fail(`"texts" is an object, one text per key: texts: { pong: 'Pong!', welcome: 'Welcome {name}!' }`);
+        }
+        const texts = new Map();
+        for (const [key, text] of Object.entries(config.texts)) {
+            texts.set(key, readText(key, text));
+        }
+        const framework = new Map();
+        if (config.framework !== undefined) {
+            if (!isRecord(config.framework)) {
+                fail(`"framework" is an object, one phrase per key: framework: { guildOnly: '...' }. It can have: ${FRAMEWORK_KEYS.join(', ')}.`);
+            }
+            for (const [key, text] of Object.entries(config.framework)) {
+                const expected = FRAMEWORK.get(key);
+                if (!expected) {
+                    fail(`"${key}" is not a phrase of the framework. It can be: ${FRAMEWORK_KEYS.join(', ')}.`);
+                }
+                const template = readText(key, text, 'phrase');
+                if (!samePlaceholders(template, expected)) {
+                    fail(`The phrase "${key}" does not have the placeholders of the framework: it has ${showParams(template.params)}, the framework has ${showParams(expected.params)}.`);
+                }
+                framework.set(key, template);
+            }
+        }
+        if (config.commands !== undefined) {
+            if (!isRecord(config.commands)) {
+                fail(`"commands" is an object whose keys are the paths of your command files: commands: { ping: { description: '...' }, 'mod/ban': { name: '...' } }`);
+            }
+            for (const [name, translation] of Object.entries(config.commands)) {
+                if (!/^[^\s]+(?: [^\s]+){0,2}$/.test(name)) {
+                    fail(`"${name}" in "commands" is not the name of a command: write it as the command declares it, like 'ping' or 'mod ban'.`);
+                }
+                if (!isRecord(translation)) {
+                    fail(`The texts of the command ${commandName(name.split(' '))} must be an object like { name: '...', description: '...' }.`);
+                }
+            }
+        }
+        return {
+            locale,
+            isDefault: config.default === true,
+            texts,
+            framework,
+            commands: config.commands,
+        };
+    },
+};
+/**
+ * Puts the languages together: one default, which `t` is typed from and
+ * gives a text to the languages that do not have it, and every other
+ * language with texts the default has, the same placeholders included. A
+ * language that does not match is left out and reported on its file: the
+ * others still work. `null` when there is no language at all.
+ */
+export function assembleMessages(entries) {
+    if (entries.length === 0)
+        return { messages: null, failed: [] };
+    const failed = [];
+    // A language may be declared in several places (the texts of one feature
+    // next to it): what says default: true decides for the whole language.
+    const byLocale = new Map();
+    for (const entry of entries) {
+        const list = byLocale.get(entry.language.locale) ?? [];
+        list.push(entry);
+        byLocale.set(entry.language.locale, list);
+    }
+    const defaults = [...byLocale.keys()].filter(locale => byLocale.get(locale).some(({ language }) => language.isDefault));
+    let defaultLocale;
+    if (byLocale.size === 1) {
+        defaultLocale = entries[0].language.locale;
+    }
+    else if (defaults.length === 1) {
+        defaultLocale = defaults[0];
+    }
+    else if (defaults.length === 0) {
+        // No default: nothing can be assembled.
+        return {
+            messages: null,
+            failed: entries.map(({ file, export: exported }) => ({
+                file,
+                export: exported,
+                error: new TypeError(`None of the ${byLocale.size} languages is the default one, used when the language of a person or of a server is not there. Add default: true in one of them.`),
+            })),
+        };
+    }
+    else {
+        const saying = entries.filter(({ language }) => language.isDefault);
+        return {
+            messages: null,
+            failed: saying.map(entry => ({
+                file: entry.file,
+                export: entry.export,
+                error: new TypeError(`${defaults.length} languages say default: true (${saying.map(one => `${one.language.locale} in ${siteName(one)}`).join(', ')}): only one can be the default.`),
+            })),
+        };
+    }
+    /** The texts of one language, from every place it is declared. */
+    const merge = (locale, what, kind, onConflict) => {
+        const merged = new Map();
+        const from = new Map();
+        for (const entry of byLocale.get(locale)) {
+            for (const [key, template] of entry.language[what]) {
+                const first = from.get(key);
+                if (first) {
+                    onConflict(entry, new TypeError(`The ${kind} "${key}" is already in ${siteName(first)}: the ${locale} language has it twice.`));
+                    continue;
+                }
+                from.set(key, entry);
+                merged.set(key, template);
+            }
+        }
+        return merged;
+    };
+    const report = (entry, error) => {
+        failed.push({ file: entry.file, export: entry.export, error });
+    };
+    const referenceTexts = merge(defaultLocale, 'texts', 'message', report);
+    const referenceSites = byLocale.get(defaultLocale);
+    const name = `the default language (${referenceSites.map(siteName).join(', ')})`;
+    // A text the default language does not have is taken from the language
+    // that has it (en-US first, then the others in order): the texts of a
+    // module written in other languages than the project's default still
+    // work, and `t` offers them. Where each such text comes from decides
+    // the placeholders every language must then follow.
+    const fallbackOrder = [...byLocale.keys()]
+        .filter(locale => locale !== defaultLocale)
+        .sort((a, b) => (a === 'en-US' ? -1 : b === 'en-US' ? 1 : a < b ? -1 : 1));
+    const fallbackFrom = new Map();
+    for (const locale of fallbackOrder) {
+        for (const entry of byLocale.get(locale)) {
+            for (const [key, template] of entry.language.texts) {
+                if (referenceTexts.has(key))
+                    continue;
+                referenceTexts.set(key, template);
+                fallbackFrom.set(key, entry);
+            }
+        }
+    }
+    const referenceName = (key) => {
+        const from = fallbackFrom.get(key);
+        return from
+            ? `${from.language.locale} (${siteName(from)}), the language this message comes from`
+            : name;
+    };
+    const locales = new Map();
+    const framework = new Map();
+    const commands = new Map();
+    const files = new Map();
+    for (const [locale, group] of byLocale) {
+        // A text a language does not have is taken from the default one (or
+        // from the language the text comes from): every language that has it
+        // must take the same placeholders.
+        const kept = [];
+        for (const entry of group) {
+            try {
+                if (locale !== defaultLocale) {
+                    for (const [key, template] of entry.language.texts) {
+                        const expected = referenceTexts.get(key);
+                        if (expected !== template &&
+                            !samePlaceholders(template, expected)) {
+                            fail(`The message "${key}" does not have the placeholders of ${referenceName(key)}: it has ${showParams([...template.params].sort())}, that one has ${showParams([...expected.params].sort())}.`);
+                        }
+                    }
+                }
+                kept.push(entry);
+            }
+            catch (error) {
+                report(entry, error);
+            }
+        }
+        if (kept.length === 0)
+            continue;
+        const texts = locale === defaultLocale
+            ? referenceTexts
+            : new Map(kept.flatMap(({ language }) => [...language.texts]));
+        if (locale !== defaultLocale) {
+            // The same message twice in a language that is not the default.
+            const from = new Map();
+            for (const entry of kept) {
+                for (const key of entry.language.texts.keys()) {
+                    const first = from.get(key);
+                    if (first) {
+                        report(entry, new TypeError(`The message "${key}" is already in ${siteName(first)}: the ${locale} language has it twice.`));
+                    }
+                    else
+                        from.set(key, entry);
+                }
+            }
+        }
+        locales.set(locale, texts);
+        const phrases = merge(locale, 'framework', 'phrase', report);
+        if (phrases.size > 0)
+            framework.set(locale, phrases);
+        files.set(locale, kept[0].file);
+        const sections = kept.filter(({ language }) => language.commands);
+        if (sections.length > 0) {
+            const translated = {};
+            const from = new Map();
+            for (const entry of sections) {
+                for (const [command, section] of Object.entries(entry.language.commands)) {
+                    const first = from.get(command);
+                    if (first) {
+                        report(entry, new TypeError(`The command "${command}" is already translated in ${siteName(first)}: the ${locale} language translates it twice.`));
+                        continue;
+                    }
+                    from.set(command, entry);
+                    translated[command] = section;
+                }
+            }
+            commands.set(locale, translated);
+        }
+    }
+    return {
+        messages: { default: defaultLocale, locales, framework, commands, files },
+        failed,
+    };
+}
+/**
+ * The augmentation that types `t` from the files themselves: the editor
+ * reads every declaration of the default language directly, so the keys
+ * and placeholders follow every keystroke; the other languages take the
+ * texts they do not have from it. `languages` is every language declared,
+ * `defaultLocale` the one `t` is typed from (the first one when it is not
+ * known yet: `sync`, which runs nothing). Nothing when the project has no
+ * language.
+ */
+export function messagesDeclarations(languages, defaultLocale) {
+    const bySite = (a, b) => a.file === b.file
+        ? a.export < b.export
+            ? -1
+            : 1
+        : a.file < b.file
+            ? -1
+            : 1;
+    const sorted = [...languages].sort(bySite);
+    const first = sorted.find(({ locale }) => locale === defaultLocale) ?? sorted[0];
+    if (!first)
+        return '';
+    // Every declaration, the default language first, then en-US, then the
+    // others: `t` knows the texts of each, the first one winning for a key
+    // several have, as the bot does.
+    const rank = (locale) => locale === first.locale ? 0 : locale === 'en-US' ? 1 : 2;
+    const ordered = [...sorted].sort((a, b) => rank(a.locale) - rank(b.locale) ||
+        (a.locale < b.locale ? -1 : a.locale > b.locale ? 1 : 0) ||
+        bySite(a, b));
+    const parts = ordered.map(one => {
+        const path = one.file.replace(/^src\//, '').replace(/\.[^./]+$/, '');
+        const member = one.export === 'default'
+            ? '.default'
+            : /^[A-Za-z_$][\w$]*$/.test(one.export)
+                ? `.${one.export}`
+                : `[${JSON.stringify(one.export)}]`;
+        return `MessagesOf<typeof import('../../src/${path}')${member}>`;
+    });
+    const where = ordered
+        .filter(({ locale }) => locale === first.locale)
+        .map(siteName)
+        .join(', ');
+    const locales = [...new Set(sorted.map(({ locale }) => locale))]
+        .map(locale => `    ${JSON.stringify(locale)}: true;`)
+        .sort()
+        .join('\n');
+    return `import type { MergedMessages, MessagesOf } from '#chapterjs';
+
+declare module 'chapterjs' {
+  /** The texts of the bot, as ${where} ${where.includes(',') ? 'write' : 'writes'} them (the ${first.locale} language), then what the other languages add: what \`t\` accepts. */
+  export interface ProjectMessages
+    extends MergedMessages<
+      [
+        ${parts.join(',\n        ')},
+      ]
+    > {}
+  /** The languages of the project: what \`t.in()\` offers. */
+  export interface ProjectLocales {
+${locales}
+  }
+}
+`;
+}
+/**
+ * The augmentation that underlines a second default language in the
+ * editor: when more than one language says `default: true` (`defaults`,
+ * the ones that do, known once the files ran), `language()` refuses
+ * `default: true` for each of them, so they are both underlined and not
+ * only reported in the console. Nothing when at most one says it.
+ */
+export function languageDefaultsDeclaration(defaults) {
+    const unique = [...new Set(defaults)].sort();
+    if (unique.length < 2)
+        return '';
+    return `export {};
+
+declare module 'chapterjs' {
+  /** The languages that say \`default: true\`: only one can be the default, so \`default: true\` is refused in each of them until one gives it up. */
+  export interface ProjectLanguageDefaults {
+${unique.map(locale => `    ${JSON.stringify(locale)}: true;`).join('\n')}
+  }
+}
+`;
+}
+/** `export default language(` or `export const fr = language(`, with the config that follows. */
+const DECLARED = /export\s+(?:default|const\s+([A-Za-z_$][\w$]*)\s*=)\s*language\s*\(\s*\{([^]*?)\}\s*\)/g;
+/**
+ * The languages of a project, found without running its files: a text
+ * search for `language({ locale: '...' })` in the exports of each file.
+ * Approximate on purpose, for `sync`, which runs nothing: `dev` and
+ * `build` then write the exact ones. Returns the languages with the one
+ * that says `default: true`, when one does.
+ */
+export async function scanLanguages(cwd) {
+    const languages = [];
+    let defaultLocale;
+    for (const { file, path } of await listSources(cwd)) {
+        const code = await readFile(path, 'utf8').catch(() => '');
+        if (!code.includes('language('))
+            continue;
+        for (const match of code.matchAll(DECLARED)) {
+            const config = match[2] ?? '';
+            const locale = /\blocale\s*:\s*['"`]([\w-]+)['"`]/.exec(config)?.[1];
+            if (!locale || !LOCALES.has(locale))
+                continue;
+            const exported = match[1] ?? 'default';
+            languages.push({
+                file,
+                export: exported,
+                name: exported === 'default' ? baseName(file) : exported,
+                locale: locale,
+            });
+            if (/\bdefault\s*:\s*true\b/.test(config)) {
+                defaultLocale ??= locale;
+            }
+        }
+    }
+    return defaultLocale === undefined
+        ? { languages }
+        : { languages, defaultLocale };
+}
+const baseName = (file) => file
+    .split('/')
+    .pop()
+    .replace(/\.[^.]+$/, '');
+/**
+ * The augmentation that offers the commands of the project in the
+ * `commands` of a language: the name of each command, `true` when the
+ * language files describe it and `false` when the command has its own
+ * `description`, so that the editor only offers the first ones. Both come
+ * from running the files (`dev` and `build` know them, `sync` does not and
+ * offers any name). Nothing when the project has no command.
+ */
+export function commandsDeclarations(commands) {
+    const entries = commands
+        .map(({ name, described }) => `    ${JSON.stringify(name)}: ${!described};`)
+        .sort();
+    if (entries.length === 0)
+        return '';
+    // A module (`export {}`), so that this augments 'chapterjs' instead of
+    // declaring it anew.
+    return `export {};
+
+declare module 'chapterjs' {
+  /** The commands of the project, by name: true when the language files describe it, false when the command has its own description. */
+  export interface ProjectCommands {
+${entries.join('\n')}
+  }
+}
+`;
+}

package/dist/messages/messages.d.ts

@@ -71,38 +71,49 @@ export interface FrameworkTexts {
     needsPermissions: MessageText;
 }
 /**
- * The commands of the project, as the editor sees them: the path of each
- * command file, `true` when the language files describe it, `false` when
- * the file has its own `description`. Filled in by the `.chapterjs/`
- * folder of the project, so that the `commands` of a language file offers
- * the ones it may translate. The options and choices are checked when the
+ * The commands of the project, as the editor sees them: the name of each
+ * command, `true` when the language files describe it, `false` when the
+ * command has its own `description`. Filled in by the `.chapterjs/` folder
+ * of the project, so that the `commands` of a language file offers the
+ * ones it may translate. The options and choices are checked when the
  * files load.
  */
 export interface ProjectCommands {
 }
-/** The paths of the commands the language files describe. */
+/** The names of the commands the language files describe. */
 type TranslatableCommand = {
     [Path in keyof ProjectCommands]: ProjectCommands[Path] extends true ? Path : never;
 }[keyof ProjectCommands];
 /**
- * What Discord shows of the commands in one language: by the path of the
- * command file (`'ping'`, `'mod/ban'`), its name, description, options and
- * choices in that language, as the `locales` of a command file take them.
- * The editor offers the commands of the project that have no `description`
- * in their file (one that has owns its texts, `locales` included); their
- * options and choices are checked when the files load.
+ * What Discord shows of the commands in one language: by the name of the
+ * command (`'ping'`, `'mod ban'`), its name, description, options and
+ * choices in that language, as the `locales` of a command take them. The
+ * editor offers the commands of the project that have no `description`
+ * (one that has owns its texts, `locales` included); their options and
+ * choices are checked when the files load.
  */
 export type CommandsTranslations = [keyof ProjectCommands] extends [never] ? Readonly<Record<string, CommandTranslation>> : [TranslatableCommand] extends [never] ? Readonly<Record<string, never>> : {
     readonly [Path in TranslatableCommand]?: CommandTranslation;
 };
-/** What a file of `src/messages/` gives to `language()`. */
-export interface LanguageConfig<T extends MessageTexts = MessageTexts> {
+/**
+ * The languages that say `default: true` when more than one does, as the
+ * editor sees them: one key per language. Filled in by the `.chapterjs/`
+ * folder of the project, so that each of them is underlined; empty when at
+ * most one language says it.
+ */
+export interface ProjectLanguageDefaults {
+}
+/** What a file gives to `language()`. */
+export interface LanguageConfig<T extends MessageTexts = MessageTexts, L extends Locale = Locale> {
+    /** The language these texts are in: `'en-US'`, `'fr'`... */
+    locale: L;
     /**
      * Whether this is the language used when the one of a person or of a
-     * server is not in `src/messages/`. Exactly one file says so; with one
-     * file, it goes without saying.
+     * server is not declared. Exactly one language says so; with one
+     * language, it goes without saying. When another language already says
+     * it, this is refused: only one can be the default.
      */
-    default?: boolean;
+    default?: L extends keyof ProjectLanguageDefaults ? false : boolean;
     /** The texts of the bot in this language, by key. */
     texts: T;
     /** What Discord shows of the commands in this language. */
@@ -141,24 +152,24 @@ export type ParamsOf<T extends MessageText> = {
 /** The arguments of `t` after the key: the params, only when there are some. */
 export type ParamsArgs<T extends MessageText> = string extends T ? [params?: Record<string, string | number>] : [Placeholders<T>] extends [never] ? [] : [params: ParamsOf<T>];
 /**
- * The languages of `src/messages/`, as the editor sees them: one key per
- * file. Filled in by the `.chapterjs/` folder of the project, empty when
- * the folder has no language.
+ * The languages of the project, as the editor sees them: one key per
+ * language declared. Filled in by the `.chapterjs/` folder of the project,
+ * empty when the project has no language.
  */
 export interface ProjectLocales {
 }
-/** A language of `src/messages/`: `'en-US'`, `'fr'`... */
+/** A language of the project: `'en-US'`, `'fr'`... */
 export type ProjectLocale = keyof ProjectLocales & string;
 /**
- * A language given to `t.in()`: the editor offers the ones of
- * `src/messages/`, and any language of Discord is accepted (the one of a
+ * A language given to `t.in()`: the editor offers the ones of the
+ * project, and any language of Discord is accepted (the one of a
  * person, of a server), `t` then taking the closest one declared. A word
  * that is no language of Discord is underlined, with the ones of the
  * project.
  */
 export type LocaleGiven<L extends string> = L extends Locale ? L : ProjectLocale;
 /**
- * `t`, as handlers receive it: gives a text of `src/messages/` in the
+ * `t`, as handlers receive it: gives a text of the language files in the
  * language of who will read the message, with its placeholders filled in.
  * `M` is the texts of the default language, which types the keys and the
  * params: a text another language does not have is taken from it.
@@ -177,43 +188,54 @@ export interface Translator<M extends object = ProjectMessages> {
     in<L extends ProjectLocale | (string & {})>(locale: LocaleGiven<L>): Translator<M>;
 }
 /**
- * The texts of `src/messages/`, as the editor sees them: the keys `t`
- * accepts and the placeholders of each. Filled in by the `.chapterjs/`
- * folder of the project when the folder has a language, empty otherwise.
+ * The texts of the project, as the editor sees them: the keys `t` accepts
+ * and the placeholders of each. Filled in by the `.chapterjs/` folder of
+ * the project when it has a language, empty otherwise.
  */
 export interface ProjectMessages {
 }
-/** What `t` is typed from, for a language file: its texts. */
-export type MessagesOf<F> = F extends LanguageFile<infer T> ? T : never;
+/** What `t` is typed from, for a language: its texts. */
+export type MessagesOf<F> = F extends LanguageDeclaration<infer T> ? T : never;
+/**
+ * The texts of several declarations, the first one winning for a key
+ * several have: what `t` is typed from when a project has several
+ * languages, the default one first, then the others (a text the default
+ * language does not have is taken from the language that has it).
+ */
+export type MergedMessages<T extends readonly object[]> = T extends readonly [
+    infer First extends object,
+    ...infer Rest extends readonly object[]
+] ? string extends keyof First ? MergedMessages<Rest> : First & Omit<MergedMessages<Rest>, keyof First> : {};
 /**
- * What every handler receives when the project has a language in
- * `src/messages/`: `t`. Nothing otherwise.
+ * What every handler receives when the project has a language: `t`.
+ * Nothing otherwise.
  */
 export type TranslationContext = [keyof ProjectMessages] extends [never] ? {} : {
-    /** The texts of `src/messages/`, in the right language. */ t: Translator;
+    /** The texts of the language files, in the right language. */ t: Translator;
 };
-/** What `language()` returns: the default export of a file of `src/messages/`. */
-export interface LanguageFile<T extends MessageTexts = MessageTexts> {
+/** What `language()` returns: a declaration the framework finds in the exports of a file. */
+export interface LanguageDeclaration<T extends MessageTexts = MessageTexts, L extends Locale = Locale> {
     /** What the file gave to `language()`, not checked yet. */
-    readonly config: LanguageConfig<T>;
+    readonly config: LanguageConfig<T, L>;
 }
 /**
- * Declares one language of the bot. Export the result as the default
- * export of a file of `src/messages/` named after the language
- * (`en-US.ts`, `fr.ts`...): every handler then receives `t`, which gives a
- * text in the language of who will read the message, with its
- * `{placeholders}` filled in.
+ * Declares one language of the bot, or more texts of it. Export the result
+ * from any file of `src/`; `locale` says which language: every handler
+ * then receives `t`, which gives a text in the language of who will read
+ * the message, with its `{placeholders}` filled in. A language may be
+ * declared in several places: the texts of a feature next to it, with the
+ * same `locale`, add to the others.
  *
  * ```ts
- * // src/messages/fr.ts
  * import { language } from 'chapterjs';
  *
  * export default language({
+ *   locale: 'fr',
  *   texts: { pong: 'Pong !', welcome: 'Bienvenue {name} !' },
  * });
  * ```
  */
-export declare function language<const T extends MessageTexts>(config: LanguageConfig<T>): LanguageFile<T>;
+export declare function language<const T extends MessageTexts, L extends Locale>(config: LanguageConfig<T, L>): LanguageDeclaration<T, L>;
 /** Whether a value was made by `language()`. */
-export declare function isLanguageFile(value: unknown): value is LanguageFile;
+export declare function isLanguageDeclaration(value: unknown): value is LanguageDeclaration;
 export {};

package/dist/messages/messages.js

@@ -1,20 +1,21 @@
-// `language()`, as the files of `src/messages/` import it from 'chapterjs':
-// every text the bot answers with in one language, and `t`, which handlers
-// receive to pick the right one.
+// `language()`, as user files import it from 'chapterjs': every text the
+// bot answers with in one language, and `t`, which handlers receive to pick
+// the right one.
 // https://docs.discord.com/developers/reference#locales
 const BRAND = Symbol.for('chapterjs.language');
 /**
- * Declares one language of the bot. Export the result as the default
- * export of a file of `src/messages/` named after the language
- * (`en-US.ts`, `fr.ts`...): every handler then receives `t`, which gives a
- * text in the language of who will read the message, with its
- * `{placeholders}` filled in.
+ * Declares one language of the bot, or more texts of it. Export the result
+ * from any file of `src/`; `locale` says which language: every handler
+ * then receives `t`, which gives a text in the language of who will read
+ * the message, with its `{placeholders}` filled in. A language may be
+ * declared in several places: the texts of a feature next to it, with the
+ * same `locale`, add to the others.
  *
  * ```ts
- * // src/messages/fr.ts
  * import { language } from 'chapterjs';
  *
  * export default language({
+ *   locale: 'fr',
  *   texts: { pong: 'Pong !', welcome: 'Bienvenue {name} !' },
  * });
  * ```
@@ -23,7 +24,7 @@ export function language(config) {
     return Object.freeze({ [BRAND]: true, config });
 }
 /** Whether a value was made by `language()`. */
-export function isLanguageFile(value) {
+export function isLanguageDeclaration(value) {
     return (typeof value === 'object' &&
         value !== null &&
         value[BRAND] === true);