Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
Translation Guide for kepler.gl
Thank you for helping translate kepler.gl! This guide explains how to add a new language or update existing translations.
Current Languages
| Code | Language | File |
|---|---|---|
en |
English | src/translations/en.ts |
fi |
Suomi (Finnish) | src/translations/fi.ts |
pt |
Português (Portuguese) | src/translations/pt.ts |
es |
Español (Spanish) | src/translations/es.ts |
ca |
Català (Catalan) | src/translations/ca.ts |
ja |
日本語 (Japanese) | src/translations/ja.ts |
cn |
简体中文 (Simplified Chinese) | src/translations/cn.ts |
ru |
Русский (Russian) | src/translations/ru.ts |
Adding a New Language
1. Create the translation file
Copy src/translations/en.ts to src/translations/<code>.ts (use the ISO 639-1 two-letter code):
cp src/translations/en.ts src/translations/de.ts
2. Translate all strings
Edit your new file and translate every string value. Keep the keys unchanged:
// src/translations/de.ts
import {LOCALES} from '../locales';
export default {
property: {
weight: 'Gewicht',
label: 'Beschriftung',
fillColor: 'Füllfarbe',
// ... translate all entries
},
// ...
};
Tips:
- Use
src/translations/en.tsas the reference for all keys - Keep placeholders like
{mapboxToken}and{errorMessage}unchanged - Preserve HTML entities and formatting strings
- For keys you're unsure about, leave the English text and add a
// TODO: translatecomment
3. Register the language
a. Add the locale to src/locales.ts:
export const LOCALES = {
en: 'English',
// ... existing locales
de: 'Deutsch' // <-- add your language
};
b. Import and add the translation in src/messages.ts:
import de from './translations/de'; // <-- add import
export const messages = {
// ... existing entries
de: flattenMessages(de) // <-- add entry
};
4. Test your translation
Set the locale in a kepler.gl instance:
import {LOCALE_CODES} from '@kepler.gl/localization';
const customizedKeplerGlReducer = keplerGlReducer
.initialState({
uiState: {
locale: LOCALE_CODES.de
}
});
Or switch languages at runtime using the locale panel in the map controls (globe icon).
Updating Existing Translations
When new English strings are added, other translation files may fall behind. To find missing translations:
- Compare your translation file against
en.tsto identify missing keys - Search for
// TODOcomments in existing translation files - Check for keys that still have English values in non-English files
Translation Structure
Translations use a nested object structure that gets flattened by flattenMessages():
{
property: {
weight: 'weight', // becomes 'property.weight'
label: 'label' // becomes 'property.label'
},
toolbar: {
exportImage: 'Export Image' // becomes 'toolbar.exportImage'
}
}
In components, strings are referenced via <FormattedMessage id="property.weight" /> or the intl.formatMessage() API.
Questions?
Open an issue on GitHub with the localization label.