0
# String Processing
1
2
String formatting, HTML escaping, and sanitization functions for secure text processing and internationalization.
3
4
## Capabilities
5
6
### String Formatting
7
8
Format strings with placeholders using object or array arguments.
9
10
```typescript { .api }
11
/**
12
* Format strings with placeholder replacement
13
* @param message - Template string with {key} placeholders
14
* @param args - Values to substitute (object or individual arguments)
15
* @returns Formatted string with placeholders replaced
16
*/
17
function format(message: string, ...args: any): string;
18
```
19
20
**Usage Examples:**
21
22
```typescript
23
import { format } from "@intlify/shared";
24
25
// Using individual arguments
26
const msg1 = format("Hello {0}, you have {1} messages", "Alice", 5);
27
// Result: "Hello Alice, you have 5 messages"
28
29
// Using object properties
30
const msg2 = format("Welcome {name}! Today is {day}.", {
31
name: "Bob",
32
day: "Monday"
33
});
34
// Result: "Welcome Bob! Today is Monday."
35
36
// Missing properties are replaced with empty string
37
const msg3 = format("Hello {name}, you have {count} items", { name: "Charlie" });
38
// Result: "Hello Charlie, you have items"
39
```
40
41
### HTML Escaping
42
43
Escape HTML special characters to prevent XSS attacks.
44
45
```typescript { .api }
46
/**
47
* Escape HTML special characters to prevent XSS
48
* @param rawText - Raw text that may contain HTML characters
49
* @returns HTML-safe escaped string
50
*/
51
function escapeHtml(rawText: string): string;
52
```
53
54
**Usage Example:**
55
56
```typescript
57
import { escapeHtml } from "@intlify/shared";
58
59
const userInput = "<script>alert('XSS')</script>";
60
const safeHtml = escapeHtml(userInput);
61
// Result: "<script>alert('XSS')</script>"
62
```
63
64
### HTML Sanitization
65
66
Sanitize translated HTML content by neutralizing dangerous elements while preserving safe markup.
67
68
```typescript { .api }
69
/**
70
* Sanitize HTML content in translations by neutralizing dangerous elements
71
* @param html - HTML content to sanitize
72
* @returns Sanitized HTML with dangerous elements neutralized
73
*/
74
function sanitizeTranslatedHtml(html: string): string;
75
```
76
77
**Usage Example:**
78
79
```typescript
80
import { sanitizeTranslatedHtml } from "@intlify/shared";
81
82
// Neutralizes event handlers and javascript: URLs
83
const dangerousHtml = '<a href="javascript:alert(1)" onclick="harm()">Click</a>';
84
const safeHtml = sanitizeTranslatedHtml(dangerousHtml);
85
// Event handlers and javascript: URLs are neutralized
86
```
87
88
### Display String Conversion
89
90
Convert values to display-friendly strings.
91
92
```typescript { .api }
93
/**
94
* Convert values to display-friendly strings
95
* @param val - Value to convert to display string
96
* @returns String representation suitable for display
97
*/
98
function toDisplayString(val: unknown): string;
99
```
100
101
**Usage Example:**
102
103
```typescript
104
import { toDisplayString } from "@intlify/shared";
105
106
console.log(toDisplayString(null)); // ""
107
console.log(toDisplayString(undefined)); // ""
108
console.log(toDisplayString([1, 2, 3])); // "[\n 1,\n 2,\n 3\n]"
109
console.log(toDisplayString({ name: "Alice" })); // "{\n \"name\": \"Alice\"\n}"
110
console.log(toDisplayString("hello")); // "hello"
111
```
112
113
### Array Joining
114
115
Join array of strings with a separator.
116
117
```typescript { .api }
118
/**
119
* Join array of strings with separator
120
* @param items - Array of strings to join
121
* @param separator - Separator to use between items (default: empty string)
122
* @returns Joined string
123
*/
124
function join(items: string[], separator?: string): string;
125
```
126
127
**Usage Example:**
128
129
```typescript
130
import { join } from "@intlify/shared";
131
132
const words = ["hello", "world", "test"];
133
console.log(join(words)); // "helloworldtest"
134
console.log(join(words, " ")); // "hello world test"
135
console.log(join(words, ", ")); // "hello, world, test"
136
```
137
138
### JSON Utilities
139
140
Safe JSON stringification with unicode character escaping.
141
142
```typescript { .api }
143
/**
144
* JSON stringify with escaped unicode line/paragraph separators
145
* @param json - Value to stringify
146
* @returns JSON string with escaped unicode characters
147
*/
148
function friendlyJSONstringify(json: unknown): string;
149
```
150
151
### Symbol Creation
152
153
Create symbols with optional global registration.
154
155
```typescript { .api }
156
/**
157
* Create symbols with optional global registration
158
* @param name - Symbol name/description
159
* @param shareable - Whether to use global symbol registry (default: false)
160
* @returns Symbol instance
161
*/
162
function makeSymbol(name: string, shareable?: boolean): symbol;
163
```
164
165
**Usage Example:**
166
167
```typescript
168
import { makeSymbol } from "@intlify/shared";
169
170
// Create unique symbol
171
const uniqueKey = makeSymbol("myKey");
172
173
// Create globally shareable symbol
174
const globalKey = makeSymbol("globalKey", true);
175
const sameGlobalKey = makeSymbol("globalKey", true);
176
console.log(globalKey === sameGlobalKey); // true
177
```
178
179
### Cache Key Generation
180
181
Generate cache keys for format operations.
182
183
```typescript { .api }
184
/**
185
* Generate cache keys for format operations
186
* @param locale - Locale identifier
187
* @param key - Message key
188
* @param source - Source string
189
* @returns Cache key string
190
*/
191
function generateFormatCacheKey(locale: string, key: string, source: string): string;
192
```
193
194
### Code Frame Generation
195
196
Generate formatted code frames for error display and debugging.
197
198
```typescript { .api }
199
/**
200
* Generate formatted code frames for error display
201
* @param source - Source code string
202
* @param start - Start position for highlighting (default: 0)
203
* @param end - End position for highlighting (default: source.length)
204
* @returns Formatted code frame with line numbers and highlighting
205
*/
206
function generateCodeFrame(source: string, start?: number, end?: number): string;
207
```
208
209
**Usage Example:**
210
211
```typescript
212
import { generateCodeFrame } from "@intlify/shared";
213
214
const code = `const message = "Hello {name}";
215
console.log(message);`;
216
217
const errorStart = code.indexOf("{name}");
218
const errorEnd = errorStart + "{name}".length;
219
220
const frame = generateCodeFrame(code, errorStart, errorEnd);
221
console.log(frame);
222
// Outputs formatted code frame with line numbers and highlighting
223
```