0
# Instance Management
1

2
Core Polyglot class for creating and managing translation instances with locale-specific phrase storage and configuration options.
3

4
## Capabilities
5

6
### Polyglot Constructor
7

8
Creates a new Polyglot instance with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Polyglot instance
13
 * @param {Object} options - Configuration options
14
 * @param {Object} options.phrases - Initial phrases object
15
 * @param {string} options.locale - Initial locale (default: 'en')
16
 * @param {boolean} options.allowMissing - Enable missing key handling
17
 * @param {Function} options.onMissingKey - Custom missing key handler function
18
 * @param {Function} options.warn - Custom warning function for missing keys
19
 * @param {Function} options.replace - Custom string replace implementation
20
 * @param {Object} options.interpolation - Token configuration object
21
 * @param {string} options.interpolation.prefix - Token prefix (default: '%{')
22
 * @param {string} options.interpolation.suffix - Token suffix (default: '}')
23
 * @param {Object} options.pluralRules - Custom pluralization rules object
24
 * @returns {Polyglot} New Polyglot instance
25
 */
26
function Polyglot(options);
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
const Polyglot = require('node-polyglot');
33

34
// Basic instance with phrases
35
const polyglot = new Polyglot({
36
  phrases: {
37
    'hello': 'Hello',
38
    'goodbye': 'Goodbye'
39
  },
40
  locale: 'en'
41
});
42

43
// Instance with custom interpolation tokens
44
const customPolyglot = new Polyglot({
45
  phrases: {
46
    'welcome': 'Welcome {{name}} to {{place}}!'
47
  },
48
  interpolation: {
49
    prefix: '{{',
50
    suffix: '}}'
51
  }
52
});
53

54
// Instance with custom missing key handler
55
const polyglotWithHandler = new Polyglot({
56
  onMissingKey: function(key, options, locale) {
57
    console.warn(`Missing translation for key: ${key}`);
58
    return `[${key}]`; // Return bracketed key as fallback
59
  }
60
});
61

62
// Instance with allowMissing enabled
63
const lenientPolyglot = new Polyglot({
64
  allowMissing: true, // Uses transformPhrase as onMissingKey handler
65
  locale: 'es'
66
});
67
```
68

69
### Instance Properties
70

71
Properties available on Polyglot instances.
72

73
```javascript { .api }
74
/**
75
 * Internal phrases storage (flattened key-value pairs)
76
 * @type {Object}
77
 */
78
phrases;
79

80
/**
81
 * Current locale setting
82
 * @type {string}
83
 */
84
currentLocale;
85

86
/**
87
 * Missing key handler function or null
88
 * @type {Function|null}
89
 */
90
onMissingKey;
91

92
/**
93
 * Warning function for missing keys
94
 * @type {Function}
95
 */
96
warn;
97

98
/**
99
 * String replace implementation function
100
 * @type {Function}
101
 */
102
replaceImplementation;
103

104
/**
105
 * Token matching regular expression
106
 * @type {RegExp}
107
 */
108
tokenRegex;
109

110
/**
111
 * Pluralization rules object
112
 * @type {Object}
113
 */
114
pluralRules;
115
```
116

117
**Usage Examples:**
118

119
```javascript
120
const polyglot = new Polyglot({
121
  phrases: { 'hello': 'Hello' },
122
  locale: 'en'
123
});
124

125
// Access instance properties
126
console.log(polyglot.phrases);        // { 'hello': 'Hello' }
127
console.log(polyglot.currentLocale);  // 'en'
128
console.log(polyglot.tokenRegex);     // /%\{(.*?)\}/g
129

130
// Properties are writable but modifying them directly is not recommended
131
// Use the provided methods instead
132
```
133

134
## Configuration Options
135

136
### Interpolation Configuration
137

138
Customize the token delimiters used for variable interpolation.
139

140
```javascript { .api }
141
interface InterpolationConfig {
142
  /** Token prefix (default: '%{') */
143
  prefix?: string;
144
  /** Token suffix (default: '}') */
145
  suffix?: string;
146
}
147
```
148

149
### Custom Missing Key Handler
150

151
Function signature for handling missing translation keys.
152

153
```javascript { .api }
154
/**
155
 * Custom handler for missing translation keys
156
 * @param {string} key - The requested translation key
157
 * @param {Object} options - Interpolation options passed to t()
158
 * @param {string} currentLocale - Current locale setting
159
 * @param {RegExp} tokenRegex - Token matching regex
160
 * @param {Object} pluralRules - Pluralization rules
161
 * @param {Function} replaceImplementation - String replace function
162
 * @returns {string} Fallback translation or transformed phrase
163
 */
164
function onMissingKey(key, options, currentLocale, tokenRegex, pluralRules, replaceImplementation);
165
```
166

167
### Plural Rules Configuration
168

169
Structure for defining custom pluralization rules.
170

171
```javascript { .api }
172
interface PluralRules {
173
  /** Mapping from plural type names to pluralization functions */
174
  pluralTypes: {
175
    [typeName: string]: (count: number) => number;
176
  };
177
  /** Mapping from plural type names to language code arrays */
178
  pluralTypeToLanguages: {
179
    [typeName: string]: string[];
180
  };
181
}
182
```