Migrated from: Leaflet#9925
Original author: danallsop
Original created: 2025-10-03T19:51:02Z
Motivation
We are close to having internationalization/translation support in Leaflet, thanks to danallsop and others (PR #9845 / #395). Great work!
As outlined in “Steps” in #395, I’d like to propose a separate GitHub repository, within the Leaflet organization to hold translation string-data for different languages.
Some key decisions are:
- Is this OK in principle?
- What file format should be used to store the translations?
- What should be the scope of translations? Is it just for Leaflet itself, or Leaflet and third-party plugins?
- What name for the repo, and NPM module? “leaflet-translations” ?
What file format?
Options include:
- Gettext PO files
- JSON files
- JavaScript files
The benefits of PO or JSON from a security standpoint is that they are data-only formats - they can’t hold executable code. PO and JS files allow for commenting, JSON doesn’t.
A dis-advantage of PO and JSON is that they would require a transformation step before use, adding complexity. As we have a relatively small number of texts to translate in Leaflet itself, PO or JSON may be overkill.
Security
For security, translation data should be kept in separate directories from any executable code. And executable code in the repository should be kept to the absolute minimum.
To prevent XSS risks, the translation strings should be plain text, not HTML.
An example of one way to create HTML markup is:
const attribution = I18n.translate('© {link}OpenStreetMap{endlink} contributors', {
link: '<a href="http://www.openstreetmap.org/copyright">',
endlink: '</a>',
});Testing
Security and other policies could be enforced using unit tests, that check that:
- translation files only contain string data,
- the strings do not contain HTML markup, and so on.
For this reason, I’m inclined to suggest the translations be held in ESM JavaScript files (example: GitHub: danallsop/maps ~ src/locale).
It is fairly straightforward to get an array of translation-objects, from ESM exports (example: GitHub: nfreear/maps ~ src/lib/localesToArray.js) — at runtime, or in a build step.
Scope of translations?
The repository could just hold translation data for Leaflet itself. Or, it could also hold translation data for third-party plugins, and even for demonstrations on the Leafletjs.com website.
If the latter, I suggest that these are kept in separate files, and are built separately.
The addition of new languages would be driven by the community. For example, via pull requests.
Tools, standards
As far as possible, use the same build, lint and test tools as used in Leaflet (eslint, karma, rollup, etc.). All JavaScript will be ESM and side-effect free, to allow tree-shaking.
File structure
A suggested file structure:
./build # Build scripts
./dist # Built files
leaflet.locale.js # Translation strings, Leaflet only.
plugins.locale.js
site.locale.js
util.js # Utility functions.
./locale
./leaflet
locale.es.js
locale.fr.js
locale.fr-ca.js # Canadian French
…
locale.zh-hans.js # Simplified Chinese
locale.zh-hant.js # Traditional Chinese
./plugins
locale.es.js # Do we have 1 file per locale for “all” plugins?
…
./site # Demonstrations on Leafletjs.com etc.
locale.es.js
…
./spec # Unit tests
./src # (Small number of) utility functions
localeToArray.js
registerAndSetLocale.js
./package.json
…
Please feedback on this proposal, in principle, and on the details.
Thanks.
Alternatives considered
No response
Motivation
We are close to having internationalization/translation support in Leaflet, thanks to danallsop and others (PR #9845 / #395). Great work!
As outlined in “Steps” in #395, I’d like to propose a separate GitHub repository, within the Leaflet organization to hold translation string-data for different languages.
Some key decisions are:
What file format?
Options include:
The benefits of PO or JSON from a security standpoint is that they are data-only formats - they can’t hold executable code. PO and JS files allow for commenting, JSON doesn’t.
A dis-advantage of PO and JSON is that they would require a transformation step before use, adding complexity. As we have a relatively small number of texts to translate in Leaflet itself, PO or JSON may be overkill.
Security
For security, translation data should be kept in separate directories from any executable code. And executable code in the repository should be kept to the absolute minimum.
To prevent XSS risks, the translation strings should be plain text, not HTML.
An example of one way to create HTML markup is:
Testing
Security and other policies could be enforced using unit tests, that check that:
For this reason, I’m inclined to suggest the translations be held in ESM JavaScript files (example: GitHub: danallsop/maps ~
src/locale).It is fairly straightforward to get an array of translation-objects, from ESM exports (example: GitHub: nfreear/maps ~
src/lib/localesToArray.js) — at runtime, or in a build step.Scope of translations?
The repository could just hold translation data for Leaflet itself. Or, it could also hold translation data for third-party plugins, and even for demonstrations on the Leafletjs.com website.
If the latter, I suggest that these are kept in separate files, and are built separately.
The addition of new languages would be driven by the community. For example, via pull requests.
Tools, standards
As far as possible, use the same build, lint and test tools as used in Leaflet (eslint, karma, rollup, etc.). All JavaScript will be ESM and side-effect free, to allow tree-shaking.
File structure
A suggested file structure:
Please feedback on this proposal, in principle, and on the details.
Thanks.
Alternatives considered
No response