Skip to content

Commit 883e23e

Browse files
david-reactpdfdavid-reactpdf
committed
Add localization README and update main README with localization section
1 parent f23eeec commit 883e23e

2 files changed

Lines changed: 192 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,20 @@ To enhance React PDF Kit further, we offer built-in hooks and props that let you
190190

191191
For detailed usage, refer to our [Documentation][reactpdf-docs].
192192

193+
### 5. Localization
194+
195+
React PDF Kit supports multiple languages out of the box. Pass a locale JSON file to `RPConfig` to translate all viewer text:
196+
197+
```jsx
198+
import zhCN from './localization/zh_CN.json'
199+
200+
<RPConfig localization={zhCN}>
201+
{/* ... */}
202+
</RPConfig>
203+
```
204+
205+
We ship locale files for English, Italian, Portuguese, Thai, and Chinese (Simplified). You can also create your own -- see the [Localization Guide](./localization/README.md) for the full list of translation keys and instructions on adding a new language. If you've created a locale we don't support yet, feel free to open a PR to share it with the community!
206+
193207
# :pushpin: Starter Toolkit
194208

195209
Here are some sample projects to get started on React PDF quickly:

‎localization/README.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Localization
2+
3+
React PDF Kit supports multiple languages through JSON locale files. This folder contains translation files that customize all user-facing text in the PDF viewer.
4+
5+
## Available Locales
6+
7+
| File | Language |
8+
| --- | --- |
9+
| `en_US.json` | English (United States) |
10+
| `it_IT.json` | Italian (Italy) |
11+
| `pt_PT.json` | Portuguese (Portugal) |
12+
| `th_TH.json` | Thai (Thailand) |
13+
| `zh_CN.json` | Chinese (Simplified) |
14+
15+
## Adding a New Locale
16+
17+
1. Copy `en_US.json` and rename it using the format `{language}_{COUNTRY}.json` (e.g., `ja_JP.json` for Japanese, `fr_FR.json` for French).
18+
2. Translate all 77 values in the file. **Do not rename any keys** -- only change the values.
19+
3. Pass your locale file to the `localization` prop on `RPConfig`:
20+
21+
```jsx
22+
import jaJP from './localization/ja_JP.json'
23+
24+
<RPConfig localization={jaJP}>
25+
{/* ... */}
26+
</RPConfig>
27+
```
28+
29+
## Translation Keys Reference
30+
31+
Each locale file is a flat JSON object. Below is a breakdown of every key grouped by feature area.
32+
33+
### Search
34+
35+
| Key | Description |
36+
| --- | --- |
37+
| `searchButtonTooltip` | Tooltip for the search button |
38+
| `searchInputPlaceholder` | Placeholder text inside the search input |
39+
| `searchInputTooltip` | Tooltip for the search input |
40+
| `searchPrevTooltip` | Tooltip for the "previous match" button |
41+
| `searchNextTooltip` | Tooltip for the "next match" button |
42+
| `searchCloseButtonTooltip` | Tooltip for the close search button |
43+
| `searchMatchCaseLabel` | Label for the "Match Case" toggle |
44+
| `searchMatchCaseTooltip` | Tooltip for the "Match Case" toggle |
45+
| `searchWholeWordsLabel` | Label for the "Whole Words" toggle |
46+
| `searchWholeWordsTooltip` | Tooltip for the "Whole Words" toggle |
47+
48+
### Navigation
49+
50+
| Key | Description |
51+
| --- | --- |
52+
| `previousPageTooltip` | Tooltip for going to the previous page |
53+
| `currentPageTooltip` | Tooltip for the current page indicator |
54+
| `nextPageTooltip` | Tooltip for going to the next page |
55+
| `firstPageLabel` | Label for the "First page" action |
56+
| `firstPageTooltip` | Tooltip for the "First page" action |
57+
| `lastPageLabel` | Label for the "Last page" action |
58+
| `lastPageTooltip` | Tooltip for the "Last page" action |
59+
60+
### Zoom
61+
62+
| Key | Description |
63+
| --- | --- |
64+
| `zoomOutTooltip` | Tooltip for the zoom out button |
65+
| `zoomInTooltip` | Tooltip for the zoom in button |
66+
| `zoomSelectTooltip` | Tooltip for the zoom level dropdown |
67+
| `zoomActualSize` | Label for the "Actual size" zoom option |
68+
| `zoomPageFit` | Label for the "Page fit" zoom option |
69+
| `zoomPageWidth` | Label for the "Page width" zoom option |
70+
71+
### Theme
72+
73+
| Key | Description |
74+
| --- | --- |
75+
| `themeEnableDarkTooltip` | Tooltip for enabling dark theme |
76+
| `themeEnableLightTooltip` | Tooltip for enabling light theme |
77+
78+
### File Operations
79+
80+
| Key | Description |
81+
| --- | --- |
82+
| `openLocalFileLabel` | Label for the "Open local file" action |
83+
| `openLocalFileTooltip` | Tooltip for the "Open local file" action |
84+
| `downloadFileLabel` | Label for the "Download file" action |
85+
| `downloadFileTooltip` | Tooltip for the "Download file" action |
86+
| `printLabel` | Label for the print action |
87+
| `printTooltip` | Tooltip for the print action |
88+
| `printLoadingMessage` | Message shown while preparing the document for print |
89+
| `printCancelLabel` | Label for the cancel button during print preparation |
90+
91+
### View Controls
92+
93+
| Key | Description |
94+
| --- | --- |
95+
| `fullScreenLabel` | Label for the full screen action |
96+
| `fullScreenTooltip` | Tooltip for the full screen action |
97+
| `moreOptionTooltip` | Tooltip for the "More options" menu |
98+
| `rotateClockwiseLabel` | Label for the rotate clockwise action |
99+
| `rotateClockwiseTooltip` | Tooltip for the rotate clockwise action |
100+
| `rotateCounterclockwiseLabel` | Label for the rotate counterclockwise action |
101+
| `rotateCounterclockwiseTooltip` | Tooltip for the rotate counterclockwise action |
102+
| `textSelectionLabel` | Label for the text selection tool |
103+
| `textSelectionTooltip` | Tooltip for the text selection tool |
104+
| `handToolLabel` | Label for the hand tool |
105+
| `handToolTooltip` | Tooltip for the hand tool |
106+
| `documentPropertiesLabel` | Label for the document properties action |
107+
| `documentPropertiesTooltip` | Tooltip for the document properties action |
108+
109+
### Scroll Modes
110+
111+
| Key | Description |
112+
| --- | --- |
113+
| `pageScrollingLabel` | Label for page scrolling mode |
114+
| `pageScrollingTooltip` | Tooltip for page scrolling mode |
115+
| `verticalScrollingLabel` | Label for vertical scrolling mode |
116+
| `verticalScrollingTooltip` | Tooltip for vertical scrolling mode |
117+
| `horizontalLabel` | Label for horizontal scrolling mode |
118+
| `horizontalTooltip` | Tooltip for horizontal scrolling mode |
119+
| `wrappedScrollingLabel` | Label for wrapped scrolling mode |
120+
| `wrappedScrollingTooltip` | Tooltip for wrapped scrolling mode |
121+
122+
### Page View Modes
123+
124+
| Key | Description |
125+
| --- | --- |
126+
| `singlePageLabel` | Label for single page view |
127+
| `singlePageTooltip` | Tooltip for single page view |
128+
| `dualPageLabel` | Label for dual page view |
129+
| `dualPageTooltip` | Tooltip for dual page view |
130+
131+
### Document Properties
132+
133+
| Key | Description |
134+
| --- | --- |
135+
| `propertiesFilenameLabel` | Label for the file name property |
136+
| `propertiesFileSizeLabel` | Label for the file size property |
137+
| `propertiesTitleLabel` | Label for the title property |
138+
| `propertiesAuthorLabel` | Label for the author property |
139+
| `propertiesSubjectLabel` | Label for the subject property |
140+
| `propertiesKeywordLabel` | Label for the keywords property |
141+
| `propertiesCreatorLabel` | Label for the creator property |
142+
| `propertiesCreateOnLabel` | Label for the creation date property |
143+
| `propertiesModifiedOnLabel` | Label for the modified date property |
144+
| `propertiesPDFProducerLabel` | Label for the PDF producer property |
145+
| `propertiesPDFVersionLabel` | Label for the PDF version property |
146+
| `propertiesPageCountLabel` | Label for the page count property |
147+
148+
### Thumbnails
149+
150+
| Key | Description |
151+
| --- | --- |
152+
| `thumbnailTooltip` | Tooltip for the thumbnail panel |
153+
154+
### Password Protected Documents
155+
156+
| Key | Description |
157+
| --- | --- |
158+
| `passwordModalTitle` | Title of the password prompt modal |
159+
| `passwordModalMessage` | Message displayed in the password prompt |
160+
| `passwordPlaceholder` | Placeholder text in the password input |
161+
| `passwordConfirmLabel` | Label for the submit button |
162+
| `passwordError` | Error message shown for incorrect password |
163+
164+
### Drag and Drop
165+
166+
| Key | Description |
167+
| --- | --- |
168+
| `dragDropFileMessage` | Message shown in the drag-and-drop zone |
169+
170+
## Contributing a New Locale
171+
172+
Created a locale file for a language we don't support yet? We'd love to include it! Please open a pull request with your new `{language}_{COUNTRY}.json` file added to this folder. Make sure all 77 keys are translated and the file is valid JSON before submitting.
173+
174+
## Tips
175+
176+
- Use `en_US.json` as the reference -- it always contains the complete set of keys.
177+
- Every key must be present in your locale file. Missing keys will fall back to the default English text.
178+
- Key names follow the pattern `{feature}{Element}{Type}` (e.g., `searchInputPlaceholder`, `zoomOutTooltip`).

0 commit comments

Comments
 (0)