1 | import { AnyJson } from '@salesforce/ts-types';
|
2 | export declare type Tokens = Array<string | boolean | number | null | undefined>;
|
3 | /**
|
4 | * A loader function to return messages.
|
5 | * @param locale The local set by the framework.
|
6 | */
|
7 | export declare type LoaderFunction = (locale: string) => Messages;
|
8 | /**
|
9 | * The core message framework manages messages and allows them to be accessible by
|
10 | * all plugins and consumers of sfdx-core. It is set up to handle localization down
|
11 | * the road at no additional effort to the consumer. Messages can be used for
|
12 | * anything from user output (like the console), to error messages, to returned
|
13 | * data from a method.
|
14 | *
|
15 | * Messages are loaded from loader functions. The loader functions will only run
|
16 | * when a message is required. This prevents all messages from being loaded into memory at
|
17 | * application startup. The functions can load from memory, a file, or a server.
|
18 | *
|
19 | * In the beginning of your app or file, add the loader functions to be used later. If using
|
20 | * json or js files in a root messages directory (`<moduleRoot>/messages`), load the entire directory
|
21 | * automatically with {@link Messages.importMessagesDirectory}. Message files must be in `.json` or `.js`
|
22 | * that exports a json object with **only** top level key-value pairs. The values support
|
23 | * [util.format](https://nodejs.org/api/util.html#util_util_format_format_args) style strings
|
24 | * that apply the tokens passed into {@link Message.getMessage}
|
25 | *
|
26 | * A sample message file.
|
27 | * ```
|
28 | * {
|
29 | * 'msgKey': 'A message displayed in the terminal'
|
30 | * }
|
31 | * ```
|
32 | *
|
33 | * **Note:** When running unit tests individually, you may see errors that the messages aren't found.
|
34 | * This is because `index.js` isn't loaded when tests run like they are when the package is required.
|
35 | * To allow tests to run, import the message directory in each test (it will only
|
36 | * do it once) or load the message file the test depends on individually.
|
37 | *
|
38 | * ```
|
39 | * // Create loader functions for all files in the messages directory
|
40 | * Messages.importMessagesDirectory(__dirname);
|
41 | *
|
42 | * // Now you can use the messages from anywhere in your code or file.
|
43 | * // If using importMessageDirectory, the bundle name is the file name.
|
44 | * const messages : Messages = Messages.loadMessages(packageName, bundleName);
|
45 | *
|
46 | * // Messages now contains all the message in the bundleName file.
|
47 | * messages.getMessage('JsonParseError');
|
48 | * ```
|
49 | */
|
50 | export declare class Messages {
|
51 | private messages;
|
52 | /**
|
53 | * Internal readFile. Exposed for unit testing. Do not use util/fs.readFile as messages.js
|
54 | * should have no internal dependencies.
|
55 | * @param filePath read file target.
|
56 | * @ignore
|
57 | */
|
58 | static _readFile: (filePath: string) => AnyJson;
|
59 | /**
|
60 | * Get the locale. This will always return 'en_US' but will return the
|
61 | * machine's locale in the future.
|
62 | */
|
63 | static getLocale(): string;
|
64 | /**
|
65 | * Set a custom loader function for a package and bundle that will be called on {@link Messages.loadMessages}.
|
66 | * @param packageName The npm package name.
|
67 | * @param bundle The name of the bundle.
|
68 | * @param loader The loader function.
|
69 | */
|
70 | static setLoaderFunction(packageName: string, bundle: string, loader: LoaderFunction): void;
|
71 | /**
|
72 | * Generate a file loading function. Use {@link Messages.importMessageFile} unless
|
73 | * overriding the bundleName is required, then manually pass the loader
|
74 | * function to {@link Messages.setLoaderFunction}.
|
75 | *
|
76 | * @param bundleName The name of the bundle.
|
77 | * @param filePath The messages file path.
|
78 | */
|
79 | static generateFileLoaderFunction(bundleName: string, filePath: string): LoaderFunction;
|
80 | /**
|
81 | * Add a single message file to the list of loading functions using the file name as the bundle name.
|
82 | * The loader will only be added if the bundle name is not already taken.
|
83 | *
|
84 | * @param packageName The npm package name.
|
85 | * @param filePath The path of the file.
|
86 | */
|
87 | static importMessageFile(packageName: string, filePath: string): void;
|
88 | /**
|
89 | * Import all json and js files in a messages directory. Use the file name as the bundle key when
|
90 | * {@link Messages.loadMessages} is called. By default, we're assuming the moduleDirectoryPart is a
|
91 | * typescript project and will truncate to root path (where the package.json file is). If your messages
|
92 | * directory is in another spot or you are not using typescript, pass in false for truncateToProjectPath.
|
93 | *
|
94 | * ```
|
95 | * // e.g. If your message directory is in the project root, you would do:
|
96 | * Messages.importMessagesDirectory(__dirname);
|
97 | * ```
|
98 | *
|
99 | * @param moduleDirectoryPath The path to load the messages folder.
|
100 | * @param truncateToProjectPath Will look for the messages directory in the project root (where the package.json file is located).
|
101 | * i.e., the module is typescript and the messages folder is in the top level of the module directory.
|
102 | * @param packageName The npm package name. Figured out from the root directory's package.json.
|
103 | */
|
104 | static importMessagesDirectory(moduleDirectoryPath: string, truncateToProjectPath?: boolean, packageName?: string): void;
|
105 | /**
|
106 | * Load messages for a given package and bundle. If the bundle is not already cached, use the loader function
|
107 | * created from {@link Messages.setLoaderFunction} or {@link Messages.importMessagesDirectory}.
|
108 | *
|
109 | * @param packageName The name of the npm package.
|
110 | * @param bundleName The name of the bundle to load.
|
111 | */
|
112 | static loadMessages(packageName: string, bundleName: string): Messages;
|
113 | /**
|
114 | * Check if a bundle already been loaded.
|
115 | * @param packageName The npm package name.
|
116 | * @param bundleName The bundle name.
|
117 | */
|
118 | static isCached(packageName: string, bundleName: string): boolean;
|
119 | private static loaders;
|
120 | private static bundles;
|
121 | /**
|
122 | * The locale of the messages in this bundle.
|
123 | */
|
124 | readonly locale: string;
|
125 | /**
|
126 | * The bundle name.
|
127 | */
|
128 | readonly bundleName: string;
|
129 | /**
|
130 | * Create a new messages bundle.
|
131 | *
|
132 | * **Note:** Use {Messages.loadMessages} unless you are writing your own loader function.
|
133 | * @param bundleName The bundle name.
|
134 | * @param locale The locale.
|
135 | * @param messages The messages. Can not be modified once created.
|
136 | */
|
137 | constructor(bundleName: string, locale: string, messages: Map<string, AnyJson>);
|
138 | /**
|
139 | * Get a message using a message key and use the tokens as values for tokenization.
|
140 | * @param key The key of the message.
|
141 | * @param tokens The values to substitute in the message.
|
142 | *
|
143 | * **See** https://nodejs.org/api/util.html#util_util_format_format_args
|
144 | */
|
145 | getMessage(key: string, tokens?: Tokens): string;
|
146 | private getMessageWithMap;
|
147 | }
|