chapterjs 0.1.1 → 0.1.4

package/dist/messages/convention.js

@@ -0,0 +1,347 @@
+// `src/messages/`: one file per language, named after it (`fr.ts` is the
+// French of the bot). 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 { commandName } from '../commands/tree.js';
+import { logicalPath, } from '../loader/loader.js';
+import { isLanguageFile } 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 = ['default', 'texts', 'commands', 'framework'];
+const EXAMPLE = `language({ 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 file is named after, or an error saying which ones exist. */
+function localeOf(path) {
+    const name = path.replace(/\.[^./]+$/, '');
+    if (name.includes('/')) {
+        fail(`A language is a file directly in src/messages/, named after the language: src/messages/${name.split('/').pop()}.ts. It can't be in a subfolder.`);
+    }
+    if (!LOCALES.has(name)) {
+        fail(`"${name}" is not a language Discord knows: the name of a file of src/messages/ is the language it holds. It can be: ${[...LOCALES].join(', ')}.`);
+    }
+    return name;
+}
+/**
+ * `src/messages/`: one file per language. Each file exports by default
+ * what `language()` returns:
+ *
+ * ```ts
+ * // src/messages/fr.ts
+ * import { language } from 'chapterjs';
+ *
+ * export default language({ texts: { pong: 'Pong !' } });
+ * ```
+ */
+export const languagesConvention = {
+    folder: 'messages',
+    one: 'language',
+    many: 'languages',
+    check(path) {
+        localeOf(path);
+    },
+    read(exports, path) {
+        const locale = localeOf(path);
+        const file = exports.default;
+        const example = `import { language } from 'chapterjs'; export default ${EXAMPLE}`;
+        if (!isLanguageFile(file)) {
+            return fail('default' in exports
+                ? `The default export of this file must be what language() returns: ${example}`
+                : `This file has no default export. It should look like: ${example}`);
+        }
+        const config = file.config;
+        if (!isRecord(config)) {
+            return fail(`language() needs an object: ${EXAMPLE}`);
+        }
+        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 [path, translation] of Object.entries(config.commands)) {
+                if (!/^[a-z0-9_-]+(?:\/[a-z0-9_-]+){0,2}$/.test(path)) {
+                    fail(`"${path}" in "commands" is not the path of a command file: write it as the file is named, like 'ping' or 'mod/ban'.`);
+                }
+                if (!isRecord(translation)) {
+                    fail(`The texts of the command ${commandName(path.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 = [];
+    const defaults = entries.filter(({ language }) => language.isDefault);
+    let reference;
+    if (entries.length === 1) {
+        reference = entries[0];
+    }
+    else if (defaults.length === 1) {
+        reference = defaults[0];
+    }
+    else if (defaults.length === 0) {
+        // No default: nothing can be assembled.
+        return {
+            messages: null,
+            failed: entries.map(({ file }) => ({
+                file,
+                error: new TypeError(`None of the ${entries.length} languages of src/messages/ 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 {
+        return {
+            messages: null,
+            failed: defaults.map(({ file }) => ({
+                file,
+                error: new TypeError(`${defaults.length} languages say default: true (${defaults.map(({ file }) => file).join(', ')}): only one can be the default.`),
+            })),
+        };
+    }
+    const locales = new Map();
+    const framework = new Map();
+    const commands = new Map();
+    const files = new Map();
+    const name = reference.file.split('/').pop();
+    for (const entry of entries) {
+        const { file, language } = entry;
+        try {
+            // A text a language does not have is taken from the default one;
+            // one the default does not have is dead: `t` offers the default's.
+            if (entry !== reference) {
+                for (const [key, template] of language.texts) {
+                    const expected = reference.language.texts.get(key);
+                    if (!expected) {
+                        fail(`The message "${key}" is not in ${name}: add it there, or remove it here.`);
+                    }
+                    if (!samePlaceholders(template, expected)) {
+                        fail(`The message "${key}" does not have the placeholders of ${name}: it has ${showParams([...template.params].sort())}, ${name} has ${showParams([...expected.params].sort())}.`);
+                    }
+                }
+            }
+            locales.set(language.locale, language.texts);
+            if (language.framework.size > 0) {
+                framework.set(language.locale, language.framework);
+            }
+            files.set(language.locale, file);
+            if (language.commands)
+                commands.set(language.locale, language.commands);
+        }
+        catch (error) {
+            failed.push({ file, error });
+        }
+    }
+    return {
+        messages: {
+            default: reference.language.locale,
+            locales,
+            framework,
+            commands,
+            files,
+        },
+        failed,
+    };
+}
+/**
+ * The augmentation that types `t` from the files themselves: the editor
+ * reads the default language of `src/messages/` directly, so the keys
+ * and placeholders follow every keystroke; the other languages take the
+ * texts they do not have from it. Which file is the default is known
+ * once the files ran (`defaultFile`, from the loaded messages): until
+ * then (`sync`), the first file is taken. Nothing when the folder has no
+ * language.
+ */
+export function messagesDeclarations(files, defaultFile) {
+    const named = namedFiles(files);
+    const first = named.find(({ file }) => file === defaultFile) ?? named[0];
+    if (!first)
+        return '';
+    const path = first.file.replace(/^src\//, '').replace(/\.[^./]+$/, '');
+    const locales = named
+        .map(({ locale }) => `    ${JSON.stringify(locale)}: true;`)
+        .sort()
+        .join('\n');
+    return `import type { MessagesOf } from '#chapterjs';
+
+declare module 'chapterjs' {
+  /** The texts of src/messages/, as ${first.file} writes them: what \`t\` accepts. */
+  export interface ProjectMessages
+    extends MessagesOf<typeof import('../../src/${path}').default> {}
+  /** The languages of src/messages/: what \`t.in()\` offers. */
+  export interface ProjectLocales {
+${locales}
+  }
+}
+`;
+}
+/** The files of `src/messages/` named after a language, with it. */
+function namedFiles(files) {
+    return files.flatMap(({ file }) => {
+        try {
+            return [{ file, locale: localeOf(file.slice('src/messages/'.length)) }];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/**
+ * One typed folder per language file: in `src/messages/fr.ts`, the
+ * `language()` imported from 'chapterjs' knows the other files. When
+ * another one says `default: true` (`defaults`, the files that do, known
+ * once they ran: `dev` and `build` give them, `sync` runs nothing), it
+ * refuses `default: true`, naming that file: a second default language is
+ * underlined in the editor, and no longer only reported in the console.
+ * Each project takes `main` (the commands a language file may translate)
+ * and not `shared`, which types `t` from the default file: a language file
+ * checked with the `language()` of another would be a false error.
+ */
+export function languageTypedFolders(files, defaults = []) {
+    return namedFiles(files).map(({ file, locale }) => {
+        const others = defaults.filter(one => one !== file).sort();
+        const refusal = others.length === 0
+            ? ''
+            : ` & {
+    /** ${others.join(' and ')} already ${others.length === 1 ? 'says' : 'say'} \`default: true\`: only one file of src/messages/ is the default language. Remove it there to make this one the default. */
+    default?: false;
+  }`;
+        return {
+            id: `messages.${locale}`,
+            folder: file,
+            includes: ['main'],
+            declarations: `import type { LanguageConfig, LanguageFile, MessageTexts } from '#chapterjs';
+
+/**
+ * Declares one language of the bot: the one this file is named after.
+ * Every handler then receives \`t\`, which gives a text in the language of
+ * who will read the message, with its \`{placeholders}\` filled in.
+ */
+export declare function language<const T extends MessageTexts>(
+  config: LanguageConfig<T>${refusal}
+): LanguageFile<T>;
+`,
+        };
+    });
+}
+/**
+ * The augmentation that offers the commands of the project in the
+ * `commands` of a language file: the path of each command file, `true`
+ * when the language files describe it and `false` when the file has its
+ * own `description`, so that the editor only offers the first ones. The
+ * path comes from the file name; whether it is described comes from
+ * running the file (`dev` and `build` know it, `sync` does not). The
+ * command files themselves are never referred to: their `t` is typed from
+ * the languages, which would be a circle. Nothing when the project has no
+ * command.
+ */
+export function commandsDeclarations(commands) {
+    const entries = commands
+        .map(({ file, described }) => {
+        const inside = file.slice('src/commands/'.length);
+        const path = logicalPath(inside).replace(/\.[^./]+$/, '');
+        return `    ${JSON.stringify(path)}: ${!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 src/commands/, by the path of their file: true when the language files describe it, false when the file has its own description. */
+  export interface ProjectCommands {
+${entries.join('\n')}
+  }
+}
+`;
+}

package/dist/messages/messages.d.ts

@@ -0,0 +1,219 @@
+import type { CommandTranslation } from '../commands/command.js';
+import type { Locale } from '../discord/types/common.js';
+/**
+ * A text with several forms, one per quantity: `t('members', { count })`
+ * picks the form of the language for that number (`one` for 1 in
+ * English, `other` for the rest; French, Russian or Arabic have others).
+ * `other` is always there; the forms a language does not use are left
+ * out. `{count}` in a form is the number itself.
+ */
+export interface PluralText {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+/**
+ * One text of a language: a string, with its `{placeholders}`, or a text
+ * with several forms, picked by `count`.
+ */
+export type MessageText = string | PluralText;
+/** The texts of one language, by key. */
+export type MessageTexts = Record<string, MessageText>;
+/**
+ * What the bot answers by itself, when it can't run what was asked: where
+ * a command or a component can't be used, a button of an old message, a
+ * `run` that failed... Every phrase has an English version; a language
+ * file gives its own in `framework`, the ones it wants. `{what}` is the
+ * word for what was used: `command`, `button`, `menu` or `form`, given
+ * here too.
+ */
+export interface FrameworkTexts {
+    /** The word for a command: "command". */
+    command: string;
+    /** The word for a button: "button". */
+    button: string;
+    /** The word for a select menu: "menu". */
+    menu: string;
+    /** The word for a form: "form". */
+    form: string;
+    /** "This {what} can only be used in a server." */
+    guildOnly: string;
+    /** "This {what} can only be used in a private message with me." */
+    dmOnly: string;
+    /** "This {what} can not be used here." */
+    notHere: string;
+    /** "This command is not available right now." (its file is gone or broken) */
+    unavailable: string;
+    /** "This {what} is not available any more." (an old message, its file is gone) */
+    gone: string;
+    /** "This {what} is out of date." (an old message, its `data` changed) */
+    outdated: string;
+    /** "Only the person who used the command can use this {what}." */
+    authorOnly: string;
+    /** "Something went wrong while running this {what}." */
+    failed: string;
+    /** "I don't have the permission to do that here." */
+    missingPermission: string;
+    /**
+     * "You can use this {what} again {when}." (a `cooldown` not over yet);
+     * `{when}` is a Discord timestamp, shown as "in 5 seconds" (or a date
+     * and time past 15 minutes) in the language of the person.
+     */
+    cooldown: string;
+    /**
+     * "You need the {permissions} permission to use this command." A plural
+     * of `count`, how many permissions are missing; `{permissions}` is their
+     * names, separated by commas.
+     */
+    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
+ * files load.
+ */
+export interface ProjectCommands {
+}
+/** The paths 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.
+ */
+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> {
+    /**
+     * 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.
+     */
+    default?: boolean;
+    /** The texts of the bot in this language, by key. */
+    texts: T;
+    /** What Discord shows of the commands in this language. */
+    commands?: CommandsTranslations;
+    /**
+     * What the bot answers by itself in this language, when it can't run
+     * what was asked: the phrases of `FrameworkTexts`, the ones this file
+     * wants to translate. The others stay in English.
+     */
+    framework?: Partial<FrameworkTexts>;
+}
+/** The text of a key, when it is one. */
+type TextOf<M, K extends keyof M> = M[K] extends MessageText ? M[K] : string;
+/**
+ * The placeholders found in a string, read from left to right like the
+ * bot does: `{{` is a `{` written as is, and a `{` with another `{` before
+ * its `}` is one too.
+ */
+type Found<S extends string> = S extends `${string}{${infer After}` ? After extends `{${infer Rest}` ? Found<Rest> : After extends `${infer Name}}${infer Rest}` ? Name extends `${string}{${string}` ? Found<After> : Name | Found<Rest> : never : never;
+/**
+ * The placeholders of a text: `'Hello {name}'` has `'name'`. Written
+ * between braces, a placeholder is a name made of letters, digits and `_`;
+ * `{{` and `}}` are braces written as is. A plural has `count`, and the
+ * placeholders of its forms.
+ */
+export type Placeholders<T extends MessageText> = T extends string ? Found<T> : T extends PluralText ? 'count' | Found<Extract<T[keyof T], string>> : never;
+/**
+ * What `t` takes for a text: one value per placeholder, or nothing when
+ * the text has none. A number is written the way the language writes
+ * numbers (`1,234` in English, `1 234` in French): give a text to keep it
+ * as is. The `count` of a plural is a number.
+ */
+export type ParamsOf<T extends MessageText> = {
+    [Name in Placeholders<T>]: Name extends 'count' ? T extends PluralText ? number : string | number : string | number;
+};
+/** 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.
+ */
+export interface ProjectLocales {
+}
+/** A language of `src/messages/`: `'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
+ * 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
+ * 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.
+ */
+export interface Translator<M extends object = ProjectMessages> {
+    <K extends keyof M & string>(key: K, ...params: ParamsArgs<TextOf<M, K>>): string;
+    /** The language the texts come from: the one asked, or the closest one declared. */
+    readonly locale: Locale;
+    /**
+     * A text in another language: `t.in('fr', 'welcome', { name })`, or
+     * `t.in(owner.locale, 'pong')`. The language of the person who will read
+     * it, when it is not the one `t` speaks.
+     */
+    in<L extends ProjectLocale | (string & {}), K extends keyof M & string>(locale: LocaleGiven<L>, key: K, ...params: ParamsArgs<TextOf<M, K>>): string;
+    /** The same `t` for another language, to write several texts: `t.in('fr')('welcome', { name })`. */
+    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.
+ */
+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 every handler receives when the project has a language in
+ * `src/messages/`: `t`. Nothing otherwise.
+ */
+export type TranslationContext = [keyof ProjectMessages] extends [never] ? {} : {
+    /** The texts of `src/messages/`, 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 the file gave to `language()`, not checked yet. */
+    readonly config: LanguageConfig<T>;
+}
+/**
+ * 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.
+ *
+ * ```ts
+ * // src/messages/fr.ts
+ * import { language } from 'chapterjs';
+ *
+ * export default language({
+ *   texts: { pong: 'Pong !', welcome: 'Bienvenue {name} !' },
+ * });
+ * ```
+ */
+export declare function language<const T extends MessageTexts>(config: LanguageConfig<T>): LanguageFile<T>;
+/** Whether a value was made by `language()`. */
+export declare function isLanguageFile(value: unknown): value is LanguageFile;
+export {};

package/dist/messages/messages.js

@@ -0,0 +1,30 @@
+// `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.
+// 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.
+ *
+ * ```ts
+ * // src/messages/fr.ts
+ * import { language } from 'chapterjs';
+ *
+ * export default language({
+ *   texts: { pong: 'Pong !', welcome: 'Bienvenue {name} !' },
+ * });
+ * ```
+ */
+export function language(config) {
+    return Object.freeze({ [BRAND]: true, config });
+}
+/** Whether a value was made by `language()`. */
+export function isLanguageFile(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[BRAND] === true);
+}

package/dist/messages/phrases.d.ts

@@ -0,0 +1,23 @@
+import type { Context } from '../structures/context.js';
+import type { FrameworkTexts } from './messages.js';
+import { type Template } from './translate.js';
+/** The phrases of the framework, in English. */
+export declare const FRAMEWORK_TEXTS: Readonly<FrameworkTexts>;
+/** A phrase of the framework. */
+export type FrameworkKey = keyof FrameworkTexts;
+/** The word for what was used, in `{what}`. */
+export type What = 'command' | 'button' | 'menu' | 'form';
+/** The phrases of the framework, compiled, by key. */
+export declare const FRAMEWORK: ReadonlyMap<FrameworkKey, Template>;
+/** The keys a language file may translate, in the order of the docs. */
+export declare const FRAMEWORK_KEYS: (keyof FrameworkTexts)[];
+/**
+ * A phrase of the framework in the language of who will read it: the one
+ * of the language file that translates it, else the English one.
+ */
+export declare function phrase(ctx: Pick<Context, 'messages'>, locale: string | null, key: FrameworkKey, params?: {
+    what?: What;
+    permissions?: string;
+    count?: number;
+    when?: string;
+}): string;

package/dist/messages/phrases.js

@@ -0,0 +1,44 @@
+// What the bot answers by itself, when it can't run what was asked: in
+// English here, and in the languages of `src/messages/` that translate
+// them (the `framework` of a language file).
+import { fill, pickLocale, templateOf } from './translate.js';
+/** The phrases of the framework, in English. */
+export const FRAMEWORK_TEXTS = Object.freeze({
+    command: 'command',
+    button: 'button',
+    menu: 'menu',
+    form: 'form',
+    guildOnly: 'This {what} can only be used in a server.',
+    dmOnly: 'This {what} can only be used in a private message with me.',
+    notHere: 'This {what} can not be used here.',
+    unavailable: 'This command is not available right now.',
+    gone: 'This {what} is not available any more.',
+    outdated: 'This {what} is out of date.',
+    authorOnly: 'Only the person who used the command can use this {what}.',
+    failed: 'Something went wrong while running this {what}.',
+    missingPermission: "I don't have the permission to do that here.",
+    cooldown: 'You can use this {what} again {when}.',
+    needsPermissions: {
+        one: 'You need the {permissions} permission to use this command.',
+        other: 'You need the {permissions} permissions to use this command.',
+    },
+});
+/** The phrases of the framework, compiled, by key. */
+export const FRAMEWORK = new Map(Object.entries(FRAMEWORK_TEXTS).map(([key, text]) => [key, templateOf(text)]));
+/** The keys a language file may translate, in the order of the docs. */
+export const FRAMEWORK_KEYS = [...FRAMEWORK.keys()];
+/**
+ * A phrase of the framework in the language of who will read it: the one
+ * of the language file that translates it, else the English one.
+ */
+export function phrase(ctx, locale, key, params = {}) {
+    const { messages } = ctx;
+    const picked = messages ? pickLocale(messages, locale) : null;
+    const own = picked ? messages.framework.get(picked)?.get(key) : undefined;
+    const template = own ?? FRAMEWORK.get(key);
+    const spoken = own ? picked : 'en-US';
+    return fill(key, template, {
+        ...params,
+        ...(params.what ? { what: phrase(ctx, locale, params.what) } : {}),
+    }, spoken);
+}