0
# Phrase Management
1

2
Methods for adding, updating, and removing translation phrases with support for nested objects, prefixing, and bulk operations.
3

4
## Capabilities
5

6
### Extend Method
7

8
Add or update phrases in the Polyglot instance, with support for nested objects and automatic key prefixing.
9

10
```javascript { .api }
11
/**
12
 * Add or update phrases (supports nested objects which get flattened)
13
 * @param {Object} morePhrases - Phrases object to add or update
14
 * @param {string} prefix - Optional prefix for all keys using dot notation
15
 */
16
extend(morePhrases, prefix);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const Polyglot = require('node-polyglot');
23

24
const polyglot = new Polyglot();
25

26
// Basic extend
27
polyglot.extend({
28
  'hello': 'Hello',
29
  'goodbye': 'Goodbye'
30
});
31

32
console.log(polyglot.phrases); 
33
// { 'hello': 'Hello', 'goodbye': 'Goodbye' }
34

35
// Extend with prefix
36
polyglot.extend({
37
  'morning': 'Good morning',
38
  'evening': 'Good evening'  
39
}, 'greetings');
40

41
console.log(polyglot.phrases);
42
// { 
43
//   'hello': 'Hello', 
44
//   'goodbye': 'Goodbye',
45
//   'greetings.morning': 'Good morning',
46
//   'greetings.evening': 'Good evening'
47
// }
48

49
// Nested object support (automatically flattened)
50
polyglot.extend({
51
  'nav': {
52
    'home': 'Home',
53
    'about': 'About',
54
    'contact': {
55
      'email': 'Email Us',
56
      'phone': 'Call Us'
57
    }
58
  }
59
});
60

61
console.log(polyglot.phrases);
62
// { 
63
//   ...existing phrases,
64
//   'nav.home': 'Home',
65
//   'nav.about': 'About', 
66
//   'nav.contact.email': 'Email Us',
67
//   'nav.contact.phone': 'Call Us'
68
// }
69

70
// Nested object with prefix
71
polyglot.extend({
72
  'login': 'Log In',
73
  'register': 'Sign Up',
74
  'settings': {
75
    'profile': 'Profile',
76
    'privacy': 'Privacy'
77
  }
78
}, 'user');
79

80
console.log(polyglot.phrases);
81
// {
82
//   ...existing phrases,
83
//   'user.login': 'Log In',
84
//   'user.register': 'Sign Up',
85
//   'user.settings.profile': 'Profile', 
86
//   'user.settings.privacy': 'Privacy'
87
// }
88

89
// Overwriting existing keys
90
polyglot.extend({
91
  'hello': 'Hi there!' // Overwrites previous 'hello'
92
});
93
```
94

95
### Unset Method
96

97
Remove phrases from the Polyglot instance by key string or object structure.
98

99
```javascript { .api }
100
/**
101
 * Remove phrases by key string or object structure
102
 * @param {string|Object} morePhrases - Key string or phrases object to remove
103
 * @param {string} prefix - Optional prefix for keys when using object form
104
 */
105
unset(morePhrases, prefix);
106
```
107

108
**Usage Examples:**
109

110
```javascript
111
const polyglot = new Polyglot({
112
  phrases: {
113
    'hello': 'Hello',
114
    'goodbye': 'Goodbye',
115
    'nav.home': 'Home',
116
    'nav.about': 'About',
117
    'user.login': 'Log In',
118
    'user.profile': 'Profile'
119
  }
120
});
121

122
// Remove single key by string
123
polyglot.unset('hello');
124
console.log(polyglot.has('hello')); // false
125

126
// Remove multiple keys using object structure
127
polyglot.unset({
128
  'home': 'Home',     // Removes 'nav.home'
129
  'about': 'About'    // Removes 'nav.about'
130
}, 'nav');
131

132
console.log(polyglot.has('nav.home'));  // false
133
console.log(polyglot.has('nav.about')); // false
134

135
// Remove nested structure 
136
polyglot.unset({
137
  'settings': {
138
    'profile': 'Profile',
139
    'privacy': 'Privacy'
140
  }
141
}, 'user');
142
// This would remove 'user.settings.profile' and 'user.settings.privacy'
143

144
// Remove object without prefix
145
polyglot.unset({
146
  'user.login': 'Log In',
147
  'user.profile': 'Profile'
148
});
149
console.log(polyglot.has('user.login'));   // false
150
console.log(polyglot.has('user.profile')); // false
151
```
152

153
### Replace Method
154

155
Completely replace all phrases with a new set, clearing existing phrases first.
156

157
```javascript { .api }
158
/**
159
 * Replace all phrases with new set (clears existing phrases first)
160
 * @param {Object} newPhrases - New phrases object to use
161
 */
162
replace(newPhrases);
163
```
164

165
**Usage Examples:**
166

167
```javascript
168
const polyglot = new Polyglot({
169
  phrases: {
170
    'old_hello': 'Old Hello',
171
    'old_goodbye': 'Old Goodbye'
172
  }
173
});
174

175
console.log(polyglot.phrases);
176
// { 'old_hello': 'Old Hello', 'old_goodbye': 'Old Goodbye' }
177

178
// Replace all phrases
179
polyglot.replace({
180
  'new_hello': 'New Hello',
181
  'new_welcome': 'Welcome',
182
  'nav': {
183
    'home': 'Home Page'
184
  }
185
});
186

187
console.log(polyglot.phrases);
188
// { 'new_hello': 'New Hello', 'new_welcome': 'Welcome', 'nav.home': 'Home Page' }
189

190
console.log(polyglot.has('old_hello'));    // false
191
console.log(polyglot.has('old_goodbye'));  // false
192
console.log(polyglot.has('new_hello'));    // true
193
```
194

195
### Clear Method
196

197
Remove all phrases from the instance.
198

199
```javascript { .api }
200
/**
201
 * Clear all phrases from the instance
202
 */
203
clear();
204
```
205

206
**Usage Examples:**
207

208
```javascript
209
const polyglot = new Polyglot({
210
  phrases: {
211
    'hello': 'Hello',
212
    'goodbye': 'Goodbye',
213
    'nav.home': 'Home'
214
  }
215
});
216

217
console.log(Object.keys(polyglot.phrases).length); // 3
218

219
// Clear all phrases
220
polyglot.clear();
221

222
console.log(Object.keys(polyglot.phrases).length); // 0
223
console.log(polyglot.phrases); // {}
224

225
// All translation attempts will now return key or use missing key handler
226
console.log(polyglot.t('hello')); // "hello" (fallback behavior)
227
```
228

229
## Nested Object Flattening
230

231
### Dot Notation Keys
232

233
Nested phrase objects are automatically flattened into dot notation keys for internal storage.
234

235
```javascript
236
// Input nested object
237
const phrases = {
238
  'app': {
239
    'title': 'My App',
240
    'sections': {
241
      'header': 'Header Text',
242
      'footer': 'Footer Text'
243
    }
244
  },
245
  'user': {
246
    'profile': {
247
      'name': 'Name',
248
      'email': 'Email Address'  
249
    }
250
  }
251
};
252

253
const polyglot = new Polyglot();
254
polyglot.extend(phrases);
255

256
// Results in flattened keys
257
console.log(polyglot.phrases);
258
// {
259
//   'app.title': 'My App',
260
//   'app.sections.header': 'Header Text',
261
//   'app.sections.footer': 'Footer Text', 
262
//   'user.profile.name': 'Name',
263
//   'user.profile.email': 'Email Address'
264
// }
265

266
// Access using flattened keys
267
polyglot.t('app.title');              // "My App"
268
polyglot.t('app.sections.header');    // "Header Text"
269
polyglot.t('user.profile.email');     // "Email Address"
270
```
271

272
### Prefix Combination
273

274
When using prefixes with nested objects, the prefix and nested keys are combined using dot notation.
275

276
```javascript
277
const polyglot = new Polyglot();
278

279
polyglot.extend({
280
  'messages': {
281
    'success': 'Operation successful',
282
    'error': {
283
      'validation': 'Validation failed',
284
      'network': 'Network error'
285
    }
286
  }
287
}, 'api');
288

289
console.log(polyglot.phrases);
290
// {
291
//   'api.messages.success': 'Operation successful',
292
//   'api.messages.error.validation': 'Validation failed', 
293
//   'api.messages.error.network': 'Network error'
294
// }
295

296
// Access with full path
297
polyglot.t('api.messages.success');              // "Operation successful"
298
polyglot.t('api.messages.error.validation');     // "Validation failed"
299
```