0
# Node Polyglot
1

2
Node Polyglot is a JavaScript internationalization (i18n) helper library that provides translation, interpolation, and pluralization capabilities. It works in both browser and Node.js environments, offering a simple solution for managing translated phrases with full support for complex pluralization rules across multiple languages.
3

4
## Package Information
5

6
- **Package Name**: node-polyglot
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install node-polyglot`
10

11
## Core Imports
12

13
```javascript
14
const Polyglot = require('node-polyglot');
15
```
16

17
For ES modules:
18

19
```javascript
20
import Polyglot from 'node-polyglot';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const Polyglot = require('node-polyglot');
27

28
// Create a new instance
29
const polyglot = new Polyglot({
30
  phrases: {
31
    'hello': 'Hello',
32
    'hello_name': 'Hello, %{name}!',
33
    'inbox': 'You have %{smart_count} messages |||| You have one message'
34
  },
35
  locale: 'en'
36
});
37

38
// Basic translation
39
polyglot.t('hello'); // "Hello"
40

41
// Translation with interpolation
42
polyglot.t('hello_name', { name: 'Alice' }); // "Hello, Alice!"
43

44
// Pluralization
45
polyglot.t('inbox', { smart_count: 0 }); // "You have 0 messages"
46
polyglot.t('inbox', { smart_count: 1 }); // "You have one message"
47
polyglot.t('inbox', { smart_count: 5 }); // "You have 5 messages"
48
```
49

50
## Architecture
51

52
Node Polyglot is built around several key components:
53

54
- **Polyglot Class**: Main interface for creating translation instances with locale-specific phrase management
55
- **Phrase Management**: Hierarchical phrase storage with dot notation support and nested object flattening
56
- **Interpolation Engine**: Token-based variable substitution with configurable delimiters and custom replacement functions
57
- **Pluralization System**: Locale-aware plural form selection supporting 13+ language types with complex rules
58
- **Static Transform Function**: Standalone phrase transformation without instance creation
59

60
## Capabilities
61

62
### Instance Management
63

64
Core Polyglot class for creating and managing translation instances with locale-specific phrase storage.
65

66
```javascript { .api }
67
/**
68
 * Creates a new Polyglot instance
69
 * @param {Object} options - Configuration options
70
 * @param {Object} options.phrases - Initial phrases object
71
 * @param {string} options.locale - Initial locale (default: 'en')
72
 * @param {boolean} options.allowMissing - Enable missing key handling
73
 * @param {Function} options.onMissingKey - Custom missing key handler
74
 * @param {Function} options.warn - Custom warning function
75
 * @param {Function} options.replace - Custom string replace implementation
76
 * @param {Object} options.interpolation - Token configuration
77
 * @param {string} options.interpolation.prefix - Token prefix (default: '%{')
78
 * @param {string} options.interpolation.suffix - Token suffix (default: '}')
79
 * @param {Object} options.pluralRules - Custom pluralization rules
80
 */
81
function Polyglot(options);
82
```
83

84
[Instance Management](./instance-management.md)
85

86
### Translation and Interpolation  
87

88
Core translation functionality with variable interpolation and default value support.
89

90
```javascript { .api }
91
/**
92
 * Translate a key with optional interpolation and pluralization
93
 * @param {string} key - Translation key
94
 * @param {Object|number} options - Interpolation options or smart_count
95
 * @param {string} options._ - Default value if key not found
96
 * @param {number} options.smart_count - Count for pluralization
97
 * @returns {string} Translated and interpolated string
98
 */
99
t(key, options);
100

101
/**
102
 * Check if translation exists for given key
103
 * @param {string} key - Translation key to check
104
 * @returns {boolean} Whether translation exists
105
 */
106
has(key);
107
```
108

109
[Translation and Interpolation](./translation-interpolation.md)
110

111
### Phrase Management
112

113
Methods for adding, updating, and removing phrases with support for nested objects and prefixing.
114

115
```javascript { .api }
116
/**
117
 * Add or update phrases (supports nested objects)
118
 * @param {Object} morePhrases - Phrases to add
119
 * @param {string} prefix - Optional prefix for all keys
120
 */
121
extend(morePhrases, prefix);
122

123
/**
124
 * Remove phrases by key or object
125
 * @param {string|Object} morePhrases - Key string or phrases object to remove
126
 * @param {string} prefix - Optional prefix for keys
127
 */
128
unset(morePhrases, prefix);
129

130
/**
131
 * Replace all phrases with new set
132
 * @param {Object} newPhrases - New phrases object
133
 */
134
replace(newPhrases);
135

136
/**
137
 * Clear all phrases
138
 */
139
clear();
140
```
141

142
[Phrase Management](./phrase-management.md)
143

144
### Pluralization
145

146
Advanced pluralization system supporting multiple languages with complex plural rules.
147

148
```javascript { .api }
149
/**
150
 * Get or set current locale
151
 * @param {string} newLocale - Optional new locale to set
152
 * @returns {string} Current locale
153
 */
154
locale(newLocale);
155

156
/**
157
 * Static method for phrase transformation without instance
158
 * @param {string} phrase - Phrase to transform
159
 * @param {Object|number} substitutions - Substitution values or smart_count
160
 * @param {string} locale - Locale for pluralization
161
 * @returns {string} Transformed phrase
162
 */
163
Polyglot.transformPhrase(phrase, substitutions, locale);
164
```
165

166
[Pluralization](./pluralization.md)
167

168
## Types
169

170
```javascript { .api }
171
/**
172
 * Polyglot constructor options
173
 * @typedef {Object} PolyglotOptions
174
 * @property {Object} phrases - Initial phrases object
175
 * @property {string} locale - Initial locale (default: 'en')
176
 * @property {boolean} allowMissing - Enable missing key handling
177
 * @property {Function} onMissingKey - Custom missing key handler
178
 * @property {Function} warn - Custom warning function
179
 * @property {Function} replace - Custom string replace implementation
180
 * @property {Object} interpolation - Token configuration
181
 * @property {string} interpolation.prefix - Token prefix (default: '%{')
182
 * @property {string} interpolation.suffix - Token suffix (default: '}')
183
 * @property {Object} pluralRules - Custom pluralization rules
184
 */
185

186
/**
187
 * Pluralization rules configuration
188
 * @typedef {Object} PluralRules
189
 * @property {Object.<string, Function>} pluralTypes - Mapping from plural type names to functions
190
 * @property {Object.<string, Array<string>>} pluralTypeToLanguages - Mapping from plural types to language codes
191
 */
192

193
/**
194
 * Translation options for t() method
195
 * @typedef {Object} TranslationOptions
196
 * @property {string} _ - Default value if key not found
197
 * @property {number} smart_count - Count for pluralization
198
 * @property {...*} [variable] - Additional variables for interpolation
199
 */
200
```