@wolfstar/plugin-i18next 1.0.0-next-20260829113016
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +169 -0
- package/dist/esm/index.d.ts +520 -0
- package/dist/esm/index.d.ts.map +1 -0
- package/dist/esm/index.js +438 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/register.d.ts +21 -0
- package/dist/esm/register.d.ts.map +1 -0
- package/dist/esm/register.js +35 -0
- package/dist/esm/register.js.map +1 -0
- package/package.json +76 -0
|
@@ -0,0 +1,520 @@
|
|
|
1
|
+
import i18next, { AppendKeyPrefix, DefaultNamespace, InitOptions, InitOptions as InitOptions$1, InterpolationMap, Namespace, ParseKeys, TFunction, TFunction as TFunction$1, TFunctionReturn, TFunctionReturnOptionalDetails, TOptions, TOptions as TOptions$1, TOptionsBase, TOptionsBase as TOptionsBase$1 } from "i18next";
|
|
2
|
+
import { Awaitable, NonNullObject } from "@sapphire/utilities";
|
|
3
|
+
import { APIApplicationCommandOptionChoice, APIInteraction, APIPingInteraction, LocaleString, LocalizationMap } from "discord-api-types/v10";
|
|
4
|
+
import { Backend } from "@wolfstar/i18next-backend";
|
|
5
|
+
import { ChokidarOptions } from "chokidar";
|
|
6
|
+
import { PathLike } from "node:fs";
|
|
7
|
+
//#region src/lib/types.d.ts
|
|
8
|
+
/**
|
|
9
|
+
* This is a re-exported type from i18next.
|
|
10
|
+
*
|
|
11
|
+
* We could use the `NoInfer` TypeScript built-in utility, however this package still supports
|
|
12
|
+
* TypeScript < 5.4.
|
|
13
|
+
*
|
|
14
|
+
* @see https://github.com/millsp/ts-toolbelt/blob/master/sources/Function/NoInfer.ts
|
|
15
|
+
*/
|
|
16
|
+
type $NoInfer<A> = [A][A extends any ? 0 : never];
|
|
17
|
+
/**
|
|
18
|
+
* This is a re-exported type from i18next. It is essentially an object of key-value pairs, where
|
|
19
|
+
* the key is a string and the value is any.
|
|
20
|
+
*/
|
|
21
|
+
interface $Dictionary {
|
|
22
|
+
[key: string]: any;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* This is a re-exported type from i18next. It is the returned type from `resolveKey` when
|
|
26
|
+
* `returnObjects` is `true` in the options.
|
|
27
|
+
*/
|
|
28
|
+
type $SpecialObject = $Dictionary | Array<string | $Dictionary>;
|
|
29
|
+
/**
|
|
30
|
+
* A translation key typed with the value it resolves to, created through {@link T}.
|
|
31
|
+
*/
|
|
32
|
+
type TypedT<TCustom = string> = string & {
|
|
33
|
+
__type__: TCustom;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* A translation key typed with both the interpolation arguments it takes and the value it resolves
|
|
37
|
+
* to, created through {@link FT}.
|
|
38
|
+
*/
|
|
39
|
+
type TypedFT<TArgs extends NonNullObject = NonNullObject, TReturn = string> = string & {
|
|
40
|
+
__args__: TArgs;
|
|
41
|
+
__return__: TReturn;
|
|
42
|
+
};
|
|
43
|
+
interface Value<T = string> {
|
|
44
|
+
value: T;
|
|
45
|
+
}
|
|
46
|
+
interface Values<T = string> {
|
|
47
|
+
values: readonly T[];
|
|
48
|
+
count: number;
|
|
49
|
+
}
|
|
50
|
+
interface Difference<T = string> {
|
|
51
|
+
previous: T;
|
|
52
|
+
next: T;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* A `commands/<file>:<key>` shaped key, used as the root key overload of {@link applyLocalizedBuilder}.
|
|
56
|
+
*/
|
|
57
|
+
type LocalePrefixKey = `commands/${string}:${string}`;
|
|
58
|
+
/**
|
|
59
|
+
* The subset of an interaction payload the localization helpers need in order to resolve a language.
|
|
60
|
+
*
|
|
61
|
+
* @remarks
|
|
62
|
+
* `@wolfstar/http-framework` receives raw Discord interaction payloads over HTTP, so the helpers
|
|
63
|
+
* operate on `discord-api-types` structures rather than on `discord.js` class instances.
|
|
64
|
+
*/
|
|
65
|
+
type Interaction = Pick<Exclude<APIInteraction, APIPingInteraction>, "locale" | "guild_locale" | "guild_id"> & Partial<Pick<Exclude<APIInteraction, APIPingInteraction>, "channel_id" | "user" | "member">>;
|
|
66
|
+
/**
|
|
67
|
+
* Any value the localization helpers accept as the source of a language.
|
|
68
|
+
*/
|
|
69
|
+
type Target = Interaction;
|
|
70
|
+
/**
|
|
71
|
+
* Configure whether to use Hot-Module-Replacement (HMR) for your i18next resources using these
|
|
72
|
+
* options. The minimum config to enable HMR is to set `enabled` to true. Any other properties are
|
|
73
|
+
* optional.
|
|
74
|
+
*/
|
|
75
|
+
interface HMROptions {
|
|
76
|
+
/**
|
|
77
|
+
* HMR status for the i18next plugin.
|
|
78
|
+
* @default false
|
|
79
|
+
*/
|
|
80
|
+
enabled: boolean;
|
|
81
|
+
/**
|
|
82
|
+
* Languages that will be reloaded when updating the languages directory.
|
|
83
|
+
* @default All languages that are automatically resolved from your folder setup
|
|
84
|
+
*/
|
|
85
|
+
languages?: string | string[];
|
|
86
|
+
/**
|
|
87
|
+
* Namespaces that will be reloaded when updating the languages directory.
|
|
88
|
+
* @default All namespaces that are automatically resolved from your languages folder setup
|
|
89
|
+
*/
|
|
90
|
+
namespaces?: string | string[];
|
|
91
|
+
/**
|
|
92
|
+
* The options passed to `chokidar`'s `watch`.
|
|
93
|
+
*/
|
|
94
|
+
options?: ChokidarOptions;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Used to dynamically add options based on the languages found in {@link InternationalizationHandler.init}.
|
|
98
|
+
*/
|
|
99
|
+
type DynamicOptions<T extends InitOptions$1> = (namespaces: string[], languages: string[]) => T;
|
|
100
|
+
/**
|
|
101
|
+
* The options used in {@link InternationalizationHandler}.
|
|
102
|
+
*/
|
|
103
|
+
interface InternationalizationOptions {
|
|
104
|
+
/**
|
|
105
|
+
* Used as the default 2nd to last fallback locale if no other is found. It's only followed by
|
|
106
|
+
* `'en-US'`.
|
|
107
|
+
*/
|
|
108
|
+
defaultName?: string;
|
|
109
|
+
/**
|
|
110
|
+
* The options passed to `backend` in `i18next.init`.
|
|
111
|
+
*/
|
|
112
|
+
backend?: Backend.Options;
|
|
113
|
+
/**
|
|
114
|
+
* The options passed to `i18next.init`.
|
|
115
|
+
*/
|
|
116
|
+
i18next?: InitOptions$1 | DynamicOptions<InitOptions$1>;
|
|
117
|
+
/**
|
|
118
|
+
* The directory in which `@wolfstar/i18next-backend` should search for files.
|
|
119
|
+
* @default `rootDirectory/languages`
|
|
120
|
+
*/
|
|
121
|
+
defaultLanguageDirectory?: string;
|
|
122
|
+
/**
|
|
123
|
+
* The default value to be used if a specific language key isn't found. Defaults to
|
|
124
|
+
* `'default:default'`.
|
|
125
|
+
*/
|
|
126
|
+
defaultMissingKey?: string;
|
|
127
|
+
/**
|
|
128
|
+
* The default namespace that is prefixed to all keys that don't specify it. Defaults to
|
|
129
|
+
* `'default'`.
|
|
130
|
+
*/
|
|
131
|
+
defaultNS?: string;
|
|
132
|
+
/**
|
|
133
|
+
* Array of formatters to add to i18next.
|
|
134
|
+
* @default []
|
|
135
|
+
*/
|
|
136
|
+
formatters?: I18nextFormatter[];
|
|
137
|
+
/**
|
|
138
|
+
* Reload languages and namespaces when updating the languages directory.
|
|
139
|
+
*/
|
|
140
|
+
hmr?: HMROptions;
|
|
141
|
+
/**
|
|
142
|
+
* A function that is to be used to retrieve the language for the current context.
|
|
143
|
+
*
|
|
144
|
+
* If this is not set, then the language will always be resolved from the interaction's locales.
|
|
145
|
+
*
|
|
146
|
+
* This will be inserted for {@link InternationalizationHandler.fetchLanguage}.
|
|
147
|
+
* @default () => null
|
|
148
|
+
*/
|
|
149
|
+
fetchLanguage?: (context: InternationalizationContext) => Awaitable<string | null>;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Context for {@link InternationalizationHandler.fetchLanguage} functions. This context enables
|
|
153
|
+
* implementation of per-guild, per-channel, and per-user localization.
|
|
154
|
+
*/
|
|
155
|
+
interface InternationalizationContext {
|
|
156
|
+
/** The ID of the guild the interaction was sent from, or `null` when sent from a DM. */
|
|
157
|
+
guildId: string | null;
|
|
158
|
+
/** The ID of the channel the interaction was sent from, or `null` when it was not provided. */
|
|
159
|
+
channelId: string | null;
|
|
160
|
+
/** The ID of the user that sent the interaction, or `null` when it was not provided. */
|
|
161
|
+
userId: string | null;
|
|
162
|
+
/** The locale the guild the interaction was sent from is configured with. */
|
|
163
|
+
interactionGuildLocale?: LocaleString;
|
|
164
|
+
/** The locale the user that sent the interaction is configured with. */
|
|
165
|
+
interactionLocale?: LocaleString;
|
|
166
|
+
}
|
|
167
|
+
interface InternationalizationClientOptions {
|
|
168
|
+
i18n?: InternationalizationOptions;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Represents a formatter that is added to i18next with `i18next.services.formatter.add` or
|
|
172
|
+
* `i18next.services.formatter.addCached`, depending on the `cached` property.
|
|
173
|
+
*
|
|
174
|
+
* @see {@link https://www.i18next.com/translation-function/formatting#adding-custom-format-function}
|
|
175
|
+
*/
|
|
176
|
+
type I18nextFormatter = I18nextNamedFormatter | I18nextNamedCachedFormatter;
|
|
177
|
+
/**
|
|
178
|
+
* Represents a formatter that is added to i18next with `i18next.services.formatter.add`.
|
|
179
|
+
*
|
|
180
|
+
* @see {@link https://www.i18next.com/translation-function/formatting#adding-custom-format-function}
|
|
181
|
+
*/
|
|
182
|
+
interface I18nextNamedFormatter {
|
|
183
|
+
cached?: false;
|
|
184
|
+
name: string;
|
|
185
|
+
format(value: any, lng: string | undefined, options: any): string;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Represents a cached formatter that is added to i18next with `i18next.services.formatter.addCached`.
|
|
189
|
+
*
|
|
190
|
+
* @see {@link https://www.i18next.com/translation-function/formatting#adding-custom-format-function}
|
|
191
|
+
*/
|
|
192
|
+
interface I18nextNamedCachedFormatter {
|
|
193
|
+
cached: true;
|
|
194
|
+
name: string;
|
|
195
|
+
format(lng: string | undefined, options: any): (value: any) => string;
|
|
196
|
+
}
|
|
197
|
+
interface LocalizedData {
|
|
198
|
+
value: string;
|
|
199
|
+
localizations: LocalizationMap;
|
|
200
|
+
}
|
|
201
|
+
interface BuilderWithName {
|
|
202
|
+
setName(name: string): this;
|
|
203
|
+
setNameLocalizations(localizedNames: LocalizationMap | null): this;
|
|
204
|
+
}
|
|
205
|
+
interface BuilderWithDescription {
|
|
206
|
+
setDescription(description: string): this;
|
|
207
|
+
setDescriptionLocalizations(localizedDescriptions: LocalizationMap | null): this;
|
|
208
|
+
}
|
|
209
|
+
type BuilderWithNameAndDescription = BuilderWithName & BuilderWithDescription;
|
|
210
|
+
//#endregion
|
|
211
|
+
//#region src/lib/InternationalizationHandler.d.ts
|
|
212
|
+
/**
|
|
213
|
+
* A generalized class for handling `i18next` JSON files and their discovery.
|
|
214
|
+
*/
|
|
215
|
+
declare class InternationalizationHandler {
|
|
216
|
+
/**
|
|
217
|
+
* Describes whether {@link InternationalizationHandler.init} has been run and languages are
|
|
218
|
+
* loaded in {@link InternationalizationHandler.languages}.
|
|
219
|
+
*/
|
|
220
|
+
languagesLoaded: boolean;
|
|
221
|
+
/**
|
|
222
|
+
* A `Set` of initially loaded namespaces.
|
|
223
|
+
*/
|
|
224
|
+
namespaces: Set<string>;
|
|
225
|
+
/**
|
|
226
|
+
* A `Map` of `i18next` language functions keyed by their language code.
|
|
227
|
+
*/
|
|
228
|
+
readonly languages: Map<string, TFunction$1<"translation", undefined>>;
|
|
229
|
+
/**
|
|
230
|
+
* The options {@link InternationalizationHandler} was initialized with.
|
|
231
|
+
*/
|
|
232
|
+
readonly options: InternationalizationOptions;
|
|
233
|
+
/**
|
|
234
|
+
* The directory passed to `@wolfstar/i18next-backend`. Also used in
|
|
235
|
+
* {@link InternationalizationHandler.walkRootDirectory}.
|
|
236
|
+
*/
|
|
237
|
+
readonly languagesDirectory: string;
|
|
238
|
+
/**
|
|
239
|
+
* The backend options for `@wolfstar/i18next-backend` used by `i18next`.
|
|
240
|
+
*/
|
|
241
|
+
protected readonly backendOptions: Backend.Options;
|
|
242
|
+
/**
|
|
243
|
+
* @param options The options that `i18next`, `@wolfstar/i18next-backend`, and
|
|
244
|
+
* {@link InternationalizationHandler} should use.
|
|
245
|
+
*/
|
|
246
|
+
constructor(options?: InternationalizationOptions);
|
|
247
|
+
/**
|
|
248
|
+
* The method to be overridden by the developer.
|
|
249
|
+
*
|
|
250
|
+
* @remarks
|
|
251
|
+
* In the event that `fetchLanguage` is not defined or returns null / undefined, the interaction's
|
|
252
|
+
* locales are used instead.
|
|
253
|
+
* @returns A string for the desired language or null for no match.
|
|
254
|
+
* @example
|
|
255
|
+
* ```typescript
|
|
256
|
+
* // Always use the same language (no per-guild configuration):
|
|
257
|
+
* container.i18n.fetchLanguage = () => 'en-US';
|
|
258
|
+
* ```
|
|
259
|
+
* @example
|
|
260
|
+
* ```typescript
|
|
261
|
+
* // Retrieving the language from an ORM:
|
|
262
|
+
* container.i18n.fetchLanguage = async (context) => {
|
|
263
|
+
* if (!context.guildId) return null;
|
|
264
|
+
* const guild = await driver.getRepository(GuildEntity).findOne({ id: context.guildId });
|
|
265
|
+
* return guild?.language ?? 'en-US';
|
|
266
|
+
* };
|
|
267
|
+
* ```
|
|
268
|
+
*/
|
|
269
|
+
fetchLanguage: (context: InternationalizationContext) => Awaitable<string | null>;
|
|
270
|
+
/**
|
|
271
|
+
* Initializes the handler by loading in the namespaces, passing the data to i18next, and filling
|
|
272
|
+
* in {@link InternationalizationHandler.languages}.
|
|
273
|
+
*/
|
|
274
|
+
init(): Promise<void>;
|
|
275
|
+
/**
|
|
276
|
+
* Retrieve a raw `TFunction` from the passed locale.
|
|
277
|
+
* @param locale The language to be used.
|
|
278
|
+
*/
|
|
279
|
+
getT(locale: string): TFunction$1<"translation", undefined>;
|
|
280
|
+
/**
|
|
281
|
+
* Localizes a content given one or more keys and i18next options.
|
|
282
|
+
* @param locale The language to be used.
|
|
283
|
+
* @param key The key or keys to retrieve the content from.
|
|
284
|
+
* @param options The interpolation options.
|
|
285
|
+
* @see {@link https://www.i18next.com/overview/api#t}
|
|
286
|
+
* @returns The localized content.
|
|
287
|
+
*/
|
|
288
|
+
format<const Key extends ParseKeys<Ns, TOpt, undefined>, const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, Ret extends TFunctionReturn<Ns, AppendKeyPrefix<Key, undefined>, TOpt> = TOpt["returnObjects"] extends true ? $SpecialObject : string, const ActualOptions extends TOpt & InterpolationMap<Ret> = TOpt & InterpolationMap<Ret>>(locale: string, key: Key | Key[], options?: ActualOptions): TFunctionReturnOptionalDetails<Ret, TOpt>;
|
|
289
|
+
/**
|
|
290
|
+
* Localizes a content given one or more keys and i18next options.
|
|
291
|
+
* @param locale The language to be used.
|
|
292
|
+
* @param key The key or keys to retrieve the content from.
|
|
293
|
+
* @param options The interpolation options as well as a `defaultValue` for the key and any
|
|
294
|
+
* key/value pairs.
|
|
295
|
+
* @see {@link https://www.i18next.com/overview/api#t}
|
|
296
|
+
* @returns The localized content.
|
|
297
|
+
*/
|
|
298
|
+
format<const Key extends ParseKeys<Ns, TOpt, undefined>, const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, Ret extends TFunctionReturn<Ns, AppendKeyPrefix<Key, undefined>, TOpt> = TOpt["returnObjects"] extends true ? $SpecialObject : string>(locale: string, key: string | string[], options: TOpt & $Dictionary & {
|
|
299
|
+
defaultValue: string;
|
|
300
|
+
}): TFunctionReturnOptionalDetails<Ret, TOpt>;
|
|
301
|
+
/**
|
|
302
|
+
* Localizes a content given one or more keys and i18next options.
|
|
303
|
+
* @param locale The language to be used.
|
|
304
|
+
* @param key The key or keys to retrieve the content from.
|
|
305
|
+
* @param defaultValue The default value to use if the key is not found.
|
|
306
|
+
* @param options The interpolation options.
|
|
307
|
+
* @see {@link https://www.i18next.com/overview/api#t}
|
|
308
|
+
* @returns The localized content.
|
|
309
|
+
*/
|
|
310
|
+
format<const Key extends ParseKeys<Ns, TOpt, undefined>, const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, Ret extends TFunctionReturn<Ns, AppendKeyPrefix<Key, undefined>, TOpt> = TOpt["returnObjects"] extends true ? $SpecialObject : string>(locale: string, key: string | string[], defaultValue: string | undefined, options?: TOpt & $Dictionary): TFunctionReturnOptionalDetails<Ret, TOpt>;
|
|
311
|
+
/**
|
|
312
|
+
* Walks the root languages directory, collecting every language and namespace found in it.
|
|
313
|
+
* @param directory The directory that should be walked.
|
|
314
|
+
*/
|
|
315
|
+
walkRootDirectory(directory: PathLike): Promise<{
|
|
316
|
+
namespaces: string[];
|
|
317
|
+
languages: string[];
|
|
318
|
+
}>;
|
|
319
|
+
/**
|
|
320
|
+
* Reloads the languages and namespaces registered in i18next, used by the HMR watcher registered
|
|
321
|
+
* in `@wolfstar/plugin-i18next/register`.
|
|
322
|
+
*/
|
|
323
|
+
reloadResources(): Promise<void>;
|
|
324
|
+
/**
|
|
325
|
+
* Walks a single locale directory, yielding every namespace found in it.
|
|
326
|
+
*
|
|
327
|
+
* @remarks
|
|
328
|
+
* Skips any file that does not end with `.json`.
|
|
329
|
+
* @param directory The directory that should be walked.
|
|
330
|
+
* @param ns The current namespace.
|
|
331
|
+
*/
|
|
332
|
+
private walkLocaleDirectory;
|
|
333
|
+
}
|
|
334
|
+
//#endregion
|
|
335
|
+
//#region src/lib/functions.d.ts
|
|
336
|
+
/**
|
|
337
|
+
* Brands a translation key with the type it resolves to.
|
|
338
|
+
* @param k The i18next key.
|
|
339
|
+
* @example
|
|
340
|
+
* ```typescript
|
|
341
|
+
* export const InvalidInput = T('path/to/file:invalidInput');
|
|
342
|
+
* ```
|
|
343
|
+
*/
|
|
344
|
+
declare function T<TCustom = string>(k: string): TypedT<TCustom>;
|
|
345
|
+
/**
|
|
346
|
+
* Brands a translation key with both its interpolation arguments and the type it resolves to.
|
|
347
|
+
* @param k The i18next key.
|
|
348
|
+
* @example
|
|
349
|
+
* ```typescript
|
|
350
|
+
* export const AddResult = FT<{ left: number; right: number; result: number }>('path/to/file:addResult');
|
|
351
|
+
* ```
|
|
352
|
+
*/
|
|
353
|
+
declare function FT<TArgs extends NonNullObject = NonNullObject, TReturn = string>(k: string): TypedFT<TArgs, TReturn>;
|
|
354
|
+
/**
|
|
355
|
+
* Every locale Discord supports.
|
|
356
|
+
*/
|
|
357
|
+
declare const supportedLanguages: ReadonlySet<LocaleString>;
|
|
358
|
+
/**
|
|
359
|
+
* Checks whether the given language is a locale Discord supports.
|
|
360
|
+
* @param language The language to check.
|
|
361
|
+
*/
|
|
362
|
+
declare function isSupportedDiscordLocale(language: string): language is LocaleString;
|
|
363
|
+
/**
|
|
364
|
+
* Resolves the loaded language that best matches the user's locale, falling back to the guild's and
|
|
365
|
+
* then to `'en-US'`.
|
|
366
|
+
* @param interaction The interaction to read the locales from.
|
|
367
|
+
*/
|
|
368
|
+
declare function getSupportedUserLanguageName(interaction: Interaction): LocaleString;
|
|
369
|
+
/**
|
|
370
|
+
* Resolves the `TFunction` for {@link getSupportedUserLanguageName}.
|
|
371
|
+
* @param interaction The interaction to read the locales from.
|
|
372
|
+
*/
|
|
373
|
+
declare function getSupportedUserLanguageT(interaction: Interaction): TFunction$1;
|
|
374
|
+
/**
|
|
375
|
+
* Resolves the loaded language that best matches the guild's locale, falling back to the user's one
|
|
376
|
+
* when the interaction was not sent from a guild, and then to `'en-US'`.
|
|
377
|
+
* @param interaction The interaction to read the locales from.
|
|
378
|
+
*/
|
|
379
|
+
declare function getSupportedLanguageName(interaction: Interaction): LocaleString;
|
|
380
|
+
/**
|
|
381
|
+
* Resolves the `TFunction` for {@link getSupportedLanguageName}.
|
|
382
|
+
* @param interaction The interaction to read the locales from.
|
|
383
|
+
*/
|
|
384
|
+
declare function getSupportedLanguageT(interaction: Interaction): TFunction$1;
|
|
385
|
+
/**
|
|
386
|
+
* Retrieves the language name for a target, using {@link InternationalizationHandler.fetchLanguage}.
|
|
387
|
+
*
|
|
388
|
+
* If that hook is not defined or returns a nullish value, there will be a series of fallback
|
|
389
|
+
* attempts in the following descending order:
|
|
390
|
+
* 1. The result of {@link getSupportedLanguageName}, if it is a loaded language.
|
|
391
|
+
* 2. {@link InternationalizationOptions.defaultName}.
|
|
392
|
+
* 3. `'en-US'`.
|
|
393
|
+
* @param target The target to fetch the language from.
|
|
394
|
+
*/
|
|
395
|
+
declare function fetchLanguage(target: Target): Promise<string>;
|
|
396
|
+
/**
|
|
397
|
+
* Retrieves the language-assigned function from i18next designated to a target's preferred language.
|
|
398
|
+
* @param target The target to fetch the language from.
|
|
399
|
+
*/
|
|
400
|
+
declare function fetchT(target: Target): Promise<TFunction$1>;
|
|
401
|
+
/**
|
|
402
|
+
* Resolves a key and its parameters using {@link fetchLanguage}, meaning a custom
|
|
403
|
+
* {@link InternationalizationHandler.fetchLanguage} hook (for example, a per-guild database lookup)
|
|
404
|
+
* is honoured.
|
|
405
|
+
*
|
|
406
|
+
* @remarks
|
|
407
|
+
* Use {@link resolveKey} when the language can be resolved from the interaction payload alone, it
|
|
408
|
+
* is synchronous and does not hit the hook.
|
|
409
|
+
* @param target The target to fetch the language key from.
|
|
410
|
+
*/
|
|
411
|
+
declare function fetchKey<const Key extends ParseKeys<Ns, TOpt, undefined>, const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, Ret extends TFunctionReturn<Ns, AppendKeyPrefix<Key, undefined>, TOpt> = TOpt["returnObjects"] extends true ? $SpecialObject : string, const ActualOptions extends TOpt & InterpolationMap<Ret> = TOpt & InterpolationMap<Ret>>(target: Target, ...[key, defaultValueOrOptions, optionsOrUndefined]: [key: Key | Key[], options?: ActualOptions] | [key: string | string[], options: TOpt & $Dictionary & {
|
|
412
|
+
defaultValue: string;
|
|
413
|
+
}] | [key: string | string[], defaultValue: string, options?: TOpt & $Dictionary]): Promise<TFunctionReturnOptionalDetails<Ret, TOpt>>;
|
|
414
|
+
/**
|
|
415
|
+
* Resolves a key with the user's language, as resolved by {@link getSupportedUserLanguageName}.
|
|
416
|
+
*/
|
|
417
|
+
declare function resolveUserKey<TReturn>(interaction: Interaction, key: TypedT<TReturn>, options?: TOptionsBase$1 | string): TReturn;
|
|
418
|
+
declare function resolveUserKey<TReturn>(interaction: Interaction, key: TypedT<TReturn>, defaultValue: TReturn, options?: TOptionsBase$1 | string): TReturn;
|
|
419
|
+
declare function resolveUserKey<TArgs extends NonNullObject, TReturn>(interaction: Interaction, key: TypedFT<TArgs, TReturn>, options?: TOptions$1<TArgs>): TReturn;
|
|
420
|
+
declare function resolveUserKey<TArgs extends NonNullObject, TReturn>(interaction: Interaction, key: TypedFT<TArgs, TReturn>, defaultValue: TReturn, options?: TOptions$1<TArgs>): TReturn;
|
|
421
|
+
declare function resolveUserKey(interaction: Interaction, key: string | string[], ...args: [any?, any?]): string;
|
|
422
|
+
/**
|
|
423
|
+
* Resolves a key with the guild's language, as resolved by {@link getSupportedLanguageName}.
|
|
424
|
+
*/
|
|
425
|
+
declare function resolveKey<TReturn>(interaction: Interaction, key: TypedT<TReturn>, options?: TOptionsBase$1 | string): TReturn;
|
|
426
|
+
declare function resolveKey<TReturn>(interaction: Interaction, key: TypedT<TReturn>, defaultValue: TReturn, options?: TOptionsBase$1 | string): TReturn;
|
|
427
|
+
declare function resolveKey<TArgs extends NonNullObject, TReturn>(interaction: Interaction, key: TypedFT<TArgs, TReturn>, options?: TOptions$1<TArgs>): TReturn;
|
|
428
|
+
declare function resolveKey<TArgs extends NonNullObject, TReturn>(interaction: Interaction, key: TypedFT<TArgs, TReturn>, defaultValue: TReturn, options?: TOptions$1<TArgs>): TReturn;
|
|
429
|
+
declare function resolveKey(interaction: Interaction, key: string | string[], ...args: [any?, any?]): string;
|
|
430
|
+
/**
|
|
431
|
+
* Gets the value and the localizations from a language key.
|
|
432
|
+
* @param key The key to get the localizations from.
|
|
433
|
+
* @returns The retrieved data.
|
|
434
|
+
* @remarks This should be called **strictly** after loading the locales.
|
|
435
|
+
*/
|
|
436
|
+
declare function getLocalizedData<const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, KPrefix = undefined>(key: ParseKeys<Ns, TOpt, KPrefix> | TypedT): LocalizedData;
|
|
437
|
+
/**
|
|
438
|
+
* Applies the localized names on the builder, calling `setName` and `setNameLocalizations`.
|
|
439
|
+
* @param builder The builder to apply the localizations to.
|
|
440
|
+
* @param key The key to get the localizations from.
|
|
441
|
+
* @returns The updated builder.
|
|
442
|
+
*/
|
|
443
|
+
declare function applyNameLocalizedBuilder<T extends BuilderWithName, const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, KPrefix = undefined>(builder: T, key: ParseKeys<Ns, TOpt, KPrefix> | TypedT): T;
|
|
444
|
+
/**
|
|
445
|
+
* Applies the localized descriptions on the builder, calling `setDescription` and
|
|
446
|
+
* `setDescriptionLocalizations`.
|
|
447
|
+
* @param builder The builder to apply the localizations to.
|
|
448
|
+
* @param key The key to get the localizations from.
|
|
449
|
+
* @returns The updated builder.
|
|
450
|
+
*/
|
|
451
|
+
declare function applyDescriptionLocalizedBuilder<T extends BuilderWithDescription, const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, KPrefix = undefined>(builder: T, key: ParseKeys<Ns, TOpt, KPrefix> | TypedT): T;
|
|
452
|
+
/**
|
|
453
|
+
* Applies the localized names and descriptions on the builder, calling
|
|
454
|
+
* {@link applyNameLocalizedBuilder} and {@link applyDescriptionLocalizedBuilder}.
|
|
455
|
+
*
|
|
456
|
+
* @param builder The builder to apply the localizations to.
|
|
457
|
+
* @param params The root key, or the key for the name and the key for the description.
|
|
458
|
+
* @returns The updated builder. You can chain subsequent builder methods on this.
|
|
459
|
+
*
|
|
460
|
+
* @remarks
|
|
461
|
+
* If only 2 parameters were passed, `name` will be defined as `${root}Name` and `description` as
|
|
462
|
+
* `${root}Description`, being `root` the second parameter in the function, after `builder`.
|
|
463
|
+
*
|
|
464
|
+
* @example
|
|
465
|
+
* ```typescript
|
|
466
|
+
* // Both keys given explicitly:
|
|
467
|
+
* applyLocalizedBuilder(builder, 'commands/names:userinfo', 'commands/descriptions:userinfo');
|
|
468
|
+
* ```
|
|
469
|
+
*
|
|
470
|
+
* @example
|
|
471
|
+
* ```typescript
|
|
472
|
+
* // Root key only, resolves `commands/userinfo:nameName` and `commands/userinfo:nameDescription`:
|
|
473
|
+
* applyLocalizedBuilder(builder, 'commands/userinfo:name');
|
|
474
|
+
* ```
|
|
475
|
+
*/
|
|
476
|
+
declare function applyLocalizedBuilder<T extends BuilderWithNameAndDescription, const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, KPrefix = undefined>(builder: T, ...params: [root: LocalePrefixKey] | [name: ParseKeys<Ns, TOpt, KPrefix> | TypedT, description: ParseKeys<Ns, TOpt, KPrefix> | TypedT]): T;
|
|
477
|
+
/**
|
|
478
|
+
* Constructs an object that can be passed into `setChoices` for a String or Number option with
|
|
479
|
+
* localized names.
|
|
480
|
+
*
|
|
481
|
+
* @param key The i18next key for the name of the choice.
|
|
482
|
+
* @param options The remaining choice options. This should _at least_ include the `value` key.
|
|
483
|
+
* @returns An object with anything provided through `options`, with `name` and `name_localizations`
|
|
484
|
+
* added.
|
|
485
|
+
*/
|
|
486
|
+
declare function createLocalizedChoice<ValueType = string | number, const TOpt extends TOptions$1 = TOptions$1, Ns extends Namespace = DefaultNamespace, KPrefix = undefined>(key: ParseKeys<Ns, TOpt, KPrefix> | TypedT, options: Omit<APIApplicationCommandOptionChoice<ValueType>, "name" | "name_localizations">): APIApplicationCommandOptionChoice<ValueType>;
|
|
487
|
+
/**
|
|
488
|
+
* Constructs a select menu option with a localized `name`, spreading any extra value on top.
|
|
489
|
+
* @param key The i18next key for the name of the select option.
|
|
490
|
+
* @param value The additional select option properties.
|
|
491
|
+
*/
|
|
492
|
+
declare function createSelectMenuChoiceName<V extends NonNullObject>(key: TypedT, value?: V): createSelectMenuChoiceName.Result<V>;
|
|
493
|
+
declare namespace createSelectMenuChoiceName {
|
|
494
|
+
type Result<V> = V & {
|
|
495
|
+
name: string;
|
|
496
|
+
name_localizations: import("discord-api-types/v10").LocalizationMap;
|
|
497
|
+
};
|
|
498
|
+
}
|
|
499
|
+
//#endregion
|
|
500
|
+
//#region src/index.d.ts
|
|
501
|
+
declare module "@sapphire/pieces" {
|
|
502
|
+
interface Container {
|
|
503
|
+
/**
|
|
504
|
+
* The internationalization handler registered by `@wolfstar/plugin-i18next`.
|
|
505
|
+
*/
|
|
506
|
+
i18n: InternationalizationHandler;
|
|
507
|
+
}
|
|
508
|
+
}
|
|
509
|
+
declare module "@wolfstar/http-framework" {
|
|
510
|
+
interface ClientOptions {
|
|
511
|
+
/**
|
|
512
|
+
* Options for the i18next-powered internationalization layer registered by
|
|
513
|
+
* `@wolfstar/plugin-i18next`.
|
|
514
|
+
*/
|
|
515
|
+
i18n?: InternationalizationOptions;
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
//#endregion
|
|
519
|
+
export { type $Dictionary, type $NoInfer, type $SpecialObject, type BuilderWithDescription, type BuilderWithName, type BuilderWithNameAndDescription, type Difference, type DynamicOptions, FT, type HMROptions, type I18nextFormatter, type I18nextNamedCachedFormatter, type I18nextNamedFormatter, type InitOptions, type Interaction, type InternationalizationClientOptions, type InternationalizationContext, InternationalizationHandler, type InternationalizationOptions, type LocalePrefixKey, type LocalizedData, T, type TFunction, type TOptions, type TOptionsBase, type Target, type TypedFT, type TypedT, type Value, type Values, applyDescriptionLocalizedBuilder, applyLocalizedBuilder, applyNameLocalizedBuilder, createLocalizedChoice, createSelectMenuChoiceName, fetchKey, fetchLanguage, fetchT, getLocalizedData, getSupportedLanguageName, getSupportedLanguageT, getSupportedUserLanguageName, getSupportedUserLanguageT, i18next, isSupportedDiscordLocale, resolveKey, resolveUserKey, supportedLanguages };
|
|
520
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/lib/types.ts","../../src/lib/InternationalizationHandler.ts","../../src/lib/functions.ts","../../src/index.ts"],"mappings":"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"}
|