0
# Translation and Interpolation
1

2
Core translation functionality providing variable interpolation, default value support, and translation key existence checking.
3

4
## Capabilities
5

6
### Translation Method (t)
7

8
The primary method for translating keys with optional interpolation and pluralization.
9

10
```javascript { .api }
11
/**
12
 * Translate a key with optional interpolation and pluralization
13
 * @param {string} key - Translation key to look up
14
 * @param {Object|number} options - Interpolation options or smart_count shortcut
15
 * @param {string} options._ - Default value if key not found
16
 * @param {number} options.smart_count - Count for pluralization
17
 * @param {...any} options.[variable] - Variables for interpolation
18
 * @returns {string} Translated and interpolated string
19
 */
20
t(key, options);
21
```
22

23
**Usage Examples:**
24

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

28
const polyglot = new Polyglot({
29
  phrases: {
30
    'hello': 'Hello',
31
    'hello_name': 'Hello, %{name}!',
32
    'welcome_user': 'Welcome %{name}, you have %{count} messages',
33
    'items_zero': 'No items',
34
    'items_one': 'One item', 
35
    'items_other': '%{smart_count} items'
36
  }
37
});
38

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

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

45
// Multiple variable interpolation  
46
polyglot.t('welcome_user', { 
47
  name: 'Bob', 
48
  count: 5 
49
}); // "Welcome Bob, you have 5 messages"
50

51
// Translation with default value
52
polyglot.t('missing_key', { 
53
  _: 'Default message' 
54
}); // "Default message"
55

56
// Pluralization using smart_count
57
polyglot.t('items', { smart_count: 0 }); // "No items"
58
polyglot.t('items', { smart_count: 1 }); // "One item"
59
polyglot.t('items', { smart_count: 5 }); // "5 items"
60

61
// Using number shortcut for smart_count
62
polyglot.t('items', 0); // "No items"
63
polyglot.t('items', 1); // "One item"
64
polyglot.t('items', 5); // "5 items"
65

66
// Missing key fallback (returns key itself by default)
67
polyglot.t('nonexistent_key'); // "nonexistent_key"
68
```
69

70
### Has Method
71

72
Check if a translation exists for a given key.
73

74
```javascript { .api }
75
/**
76
 * Check if translation exists for given key
77
 * @param {string} key - Translation key to check
78
 * @returns {boolean} True if translation exists, false otherwise
79
 */
80
has(key);
81
```
82

83
**Usage Examples:**
84

85
```javascript
86
const polyglot = new Polyglot({
87
  phrases: {
88
    'hello': 'Hello',
89
    'nested.key': 'Nested value'
90
  }
91
});
92

93
// Check existing keys
94
polyglot.has('hello'); // true
95
polyglot.has('nested.key'); // true
96

97
// Check non-existent keys
98
polyglot.has('goodbye'); // false
99
polyglot.has('nested.missing'); // false
100

101
// Use has() to conditionally translate
102
if (polyglot.has('optional_message')) {
103
  console.log(polyglot.t('optional_message'));
104
} else {
105
  console.log('No optional message available');
106
}
107

108
// Provide fallback translations
109
const message = polyglot.has('custom_greeting') 
110
  ? polyglot.t('custom_greeting', { name: 'User' })
111
  : polyglot.t('default_greeting', { name: 'User' });
112
```
113

114
## Interpolation System
115

116
### Variable Interpolation
117

118
Replace tokens in translated phrases with provided values.
119

120
**Token Format:**
121
- Default: `%{variable_name}`
122
- Configurable via interpolation options in constructor
123

124
**Interpolation Rules:**
125
- Missing variables remain as-is in the output
126
- Null/undefined values are treated as missing
127
- Variables can be any type that converts to string
128

129
```javascript
130
const polyglot = new Polyglot({
131
  phrases: {
132
    'user_info': 'User: %{name}, Age: %{age}, Active: %{active}',
133
    'partial': 'Hello %{name}, your score is %{score}'
134
  }
135
});
136

137
// Complete interpolation
138
polyglot.t('user_info', {
139
  name: 'Alice',
140
  age: 25,
141
  active: true
142
}); // "User: Alice, Age: 25, Active: true"
143

144
// Partial interpolation (missing variables remain)
145
polyglot.t('partial', { 
146
  name: 'Bob' 
147
}); // "Hello Bob, your score is %{score}"
148

149
// Null/undefined values treated as missing
150
polyglot.t('partial', { 
151
  name: 'Charlie',
152
  score: null
153
}); // "Hello Charlie, your score is %{score}"
154
```
155

156
### Default Values
157

158
Provide fallback text when translation keys are missing.
159

160
```javascript
161
const polyglot = new Polyglot({
162
  phrases: {
163
    'existing': 'This exists'
164
  }
165
});
166

167
// Use default value for missing key
168
polyglot.t('missing_key', {
169
  _: 'This is the default value'
170
}); // "This is the default value"
171

172
// Default value with interpolation
173
polyglot.t('missing_greeting', {
174
  _: 'Hello, %{name}!',
175
  name: 'World'
176
}); // "Hello, World!"
177

178
// Existing key takes precedence over default
179
polyglot.t('existing', {
180
  _: 'This default will be ignored'
181
}); // "This exists"
182
```
183

184
## Error Handling
185

186
### Missing Key Behavior
187

188
Default behavior when translation keys are not found:
189

190
1. Check for `_` (underscore) default value in options
191
2. Call custom `onMissingKey` handler if configured  
192
3. Display warning message if warn function is set
193
4. Return the key itself as fallback
194

195
```javascript
196
// Default behavior - returns key
197
const polyglot = new Polyglot();
198
polyglot.t('missing'); // "missing"
199

200
// Custom missing key handler
201
const customPolyglot = new Polyglot({
202
  onMissingKey: (key) => `[MISSING: ${key}]`
203
});
204
customPolyglot.t('missing'); // "[MISSING: missing]"
205

206
// Allow missing keys (uses transformPhrase as handler)
207
const lenientPolyglot = new Polyglot({
208
  allowMissing: true
209
});
210
lenientPolyglot.t('missing', { smart_count: 1 }); // "missing"
211
```