Skip to content

Split developer localization info out of the translator page #543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Split developer localization info out of the translator page #543

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
42f0a15
Initial plan
Copilot Feb 25, 2026
0446f82
Split developer info out of translating-ui.md into new developer-guid…
Copilot Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions docs/technical-reference/developer-guide-to-localization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
---
id: developer-guide-to-localization
title: Developer guide to localization
sidebar_label: Localizing OpenRefine
---

This page explains how developers should handle localization when writing or modifying OpenRefine's front end and back end. For information on contributing translations, see [Translate OpenRefine's interface](translating-ui).

## Translation format {#translation-format}

Localized strings are entered in a `.json` file, one per language. They are located in the folder `main/webapp/modules/core/langs/` in a file named `translation-xx.json`, where `xx` is the language code (i.e. `fr` for French).

### Simple case of localized string {#simple-case-of-localized-string}
This is an example of a simple string, with the start of the JSON file. This example is for French.
```
{
"name": "Français",
"core-index/help": "Aide",
(… more lines)
}
```

So the key `core-index/help` will render as `"Aide"` in French.

### Localization with a parameterized value {#localization-with-a-parameterized-value}
In this example, the name of the column (represented by `$1` in this example), will be substituted with the string of the name of the column.

`"core-facets/edit-facet-title": "Cliquez ici pour éditer le nom de la facette\nColonne : $1",`

### Localization with a singular/plural value {#localization-with-a-singularplural-value}

In this example, one of the parameters will have a different string depending on whether the value is 1 or another value. The string for page, the second parameter `$2`, will have an « s » or not depending on the value of `$2`.

`"core-views/goto-page": "$1 de $2 {{plural:$2|page|pages}}"`

#### Languages with more than two plural forms {#languages-with-more-plural-forms}

Some languages have more than two plural forms. For example, Russian has three forms (one, few, many) and Arabic has six (zero, one, two, few, many, other). The `{{plural:$n|...}}` syntax supports these through [CLDR plural rules](https://cldr.unicode.org/index/cldr-spec/plural-rules).

You can specify named CLDR keyword forms:

```
{{plural:$1|one=singular form|few=few form|many=many form|other=default form}}
```

The English default strings should use the simple `one|other` positional syntax. Translators for languages with more complex plural rules should use the named keyword syntax in their translation files.

## Front-end development {#front-end-development}

The OpenRefine front end has been localized using the [Wikimedia jquery.i18n library](https://github.com/wikimedia/jquery.i18n). The localized text is stored in a JSON dictionary on the server and retrieved with a new OpenRefine command.

### Adding a new string {#adding-a-new-string}

There should be no hard-coded language strings in the HTML or JSON used for the front end. If you need a new string, first check the existing strings to make sure there isn't an equivalent string, **in an equivalent context**, that you can reuse. Context is important because it can affect how the same literal English text is translated. This cuts down on the amount of text which needs to be translated.

Strings should be entire sentences or phrases and should include substitution variables for any parameters. Do not concatenate strings in either Java or JavaScript (or implicitly by laying them out in a specific order in the HTML). So, instead of `"You have " + count + " row(s)"` (or worse `count != 1 ? " rows" : " row"`), internationalize everything together so that it can be translated taking into account word ordering and plurals for different languages, ie `"You have $1 {{plural:$1|row|rows}}"`, passing the parameter(s) into the `$.i18n` call.

This is especially important for non-Indo-European languages, where word order, agreement, and grammatical structure can differ greatly from English. Concatenating fragments, or composing a sentence by positioning elements with CSS or HTML layout, makes it impossible for translators to produce natural-sounding results.

If there's no string you can reuse, allocate an available key in the appropriate translation dictionary and add the default string, e.g.

```json
...,
"section/newkey": "new default string for this key",
...
```

and then set the text (or HTML) of your HTML element using i18n helper method. So given an HTML fragment like:
```html
<label id="new-element-id">[untranslated text would have appeared here before]</label>
```
we could set its text using:
```javascript
$('#new-html-element-id').text($.i18n('section/newkey'));
```
or, if you need to embed HTML tags:
```javascript
$('#new-html-element-id').html($.i18n('section/newkey'));
```

HTML should be avoided as it can enable [cross-scripting attacks](https://owasp.org/www-community/attacks/xss/).

### Adding a new language {#adding-a-new-language}

The language dictionaries are stored in the `langs` subdirectory for the module e.g.

* https://github.com/OpenRefine/OpenRefine/tree/master/main/webapp/modules/core/langs for the main interface
* https://github.com/OpenRefine/OpenRefine/tree/master/extensions/database/module/langs for database via JDBC
* https://github.com/OpenRefine/OpenRefine/tree/master/extensions/wikibase/module/langs for the Wikibase extension

To add support for a new language, the easiest way is to do it directly in Weblate. To do it manually, copy `translation-en.json` to `translation-<locale>.json` and have your translator translate all the value strings (ie right hand side).

Once the translation file is in place, register the language in the dropdown menu in `/OpenRefine/main/webapp/modules/core/scripts/index/lang-settings-ui.html`. The entry should look like:
```html
<option value="<locale>">[Language Label]</option>
```

By default, the system tries to load the language file corresponding to the currently in-use browser language. The "Language Settings" menu item on the index page allows users to override this setting.

## Server-side localisation {#server-side-localisation}

Certain areas of the back-end can also be localized, also via Weblate.
The translated strings are stored in `.properties` file, from which Java classes are generated at compilation time.
For instance, operation descriptions are stored under [`main/resources/com/google/refine/operations`](https://github.com/OpenRefine/OpenRefine/tree/master/main/resources/com/google/refine/operations/).
93 changes: 7 additions & 86 deletions docs/technical-reference/translating-ui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,97 +10,18 @@ You can help translate OpenRefine into your language by visiting [Weblate](https

Click to help translate --> [Weblate](https://hosted.weblate.org/engage/openrefine/?utm_source=widget)

## Manual translation process {#manual-translation-process}

Localized strings are entered in a `.json` file, one per language. They are located in the folder `main/webapp/modules/core/langs/` in a file named `translation-xx.json`, where `xx` is the language code (i.e. `fr` for French).
The translation is best done [with Weblate](https://hosted.weblate.org/engage/openrefine/?utm_source=widget). Changes are pushed to OpenRefine's git repository and are included in the next release.

### Simple case of localized string {#simple-case-of-localized-string}
This is an example of a simple string, with the start of the JSON file. This example is for French.
```
{
"name": "Français",
"core-index/help": "Aide",
(… more lines)
}
```
[Run OpenRefine from the master branch](/docs/technical-reference/build-test-run) and check whether translated words fit to the layout. Not all items can be translated word by word, especially into non-Ìndo-European languages.

So the key `core-index/help` will render as `"Aide"` in French.
If you see any text which remains in English even when you have checked all items, please create a bug report in the issue tracker so that the developers can fix it. Similarly report any cases where the developers have used string concatenation or layout to compose multi-part strings, rather than using the localization facilities.
Copy link
Copy Markdown
Member

@magdmartin magdmartin Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we recommend to open the bug on the main Github bug tracker (https://github.com/OpenRefine/OpenRefine/issues/new?template=bug_report.md ) and then the team triage the right repo? This would be the case if the missing translation is on an extension.


### Localization with a parameterized value {#localization-with-a-parameterized-value}
In this example, the name of the column (represented by `$1` in this example), will be substituted with the string of the name of the column.

`"core-facets/edit-facet-title": "Cliquez ici pour éditer le nom de la facette\nColonne : $1",`

### Localization with a singular/plural value {#localization-with-a-singularplural-value}
In this example, one of the parameter will have a different string depending if the value is 1 or another value.
In this example, the string for page, the second parameter, `$2`, will have an « s » or not depending on the value of `$2`.

`"core-views/goto-page": "$1 de $2 {{plural:$2|page|pages}}"`

## Front-end development {#front-end-development}

The OpenRefine front end has been localized using the [Wikimedia jquery.i18n library](https://github.com/wikimedia/jquery.i18n). The localized text is stored in a JSON dictionary on the server and retrieved with a new OpenRefine command.

### Adding a new string {#adding-a-new-string}

There should be no hard-coded language strings in the HTML or JSON used for the front end. If you need a new string, first check the existing strings to make sure there isn't an equivalent string, **in an equivalent context**, that you can reuse. Context is important because it can affect how the same literal English text is translated. This cuts down on the amount of text which needs to be translated.

Strings should be entire sentences or phrases and should include substitution variables for any parameters. Do not concatenate strings in either Java or Javascript (or implicitly by laying them out in a specific order). So, instead of `"You have " + count + " row(s)"` (or worse `count != 1 ? " rows" : " row"`), internationalize everything together so that it can be translated taking into account word ordering and plurals for different languages, ie `"You have $1 {{plural $1: row|rows}}"`, passing the parameter(s) into the `$.i18n` call.

If there's no string you can reuse, allocate an available key in the appropriate translation dictionary and add the default string, e.g.

```json
...,
"section/newkey": "new default string for this key",
...
```

and then set the text (or HTML) of your HTML element using i18n helper method. So given an HTML fragment like:
```html
<label id="new-element-id">[untranslated text would have appeared here before]</label>
```
we could set its text using:
```
$('#new-html-element-id').text($.i18n('section/newkey'));
```
or, if you need to embed HTML tags:
```
$('#new-html-element-id').html($.i18n('section/newkey'));
```

HTML should be avoided as it can enable [cross-scripting attacks](https://owasp.org/www-community/attacks/xss/).

### Adding a new language {#adding-a-new-language}

The language dictionaries are stored in the `langs` subdirectory for the module e.g.

* https://github.com/OpenRefine/OpenRefine/tree/master/main/webapp/modules/core/langs for the main interface
* https://github.com/OpenRefine/OpenRefine/tree/master/extensions/database/module/langs for database via JDBC
* https://github.com/OpenRefine/OpenRefine/tree/master/extensions/wikibase/module/langs for the Wikibase extension

To add support for a new language, the easiest way is to do it directly in Weblate. To do it manually, copy `translation-en.json` to `translation-<locale>.json` and have your translator translate all the value strings (ie right hand side).

#### Main interface {#main-interface}
The translation is best done [with Weblate](https://hosted.weblate.org/engage/openrefine/?utm_source=widget). Changes are pushed to OpenRefine's git repository and are included in the next release.

[Run OpenRefine from the master branch](/docs/technical-reference/build-test-run) and check whether translated words fit to the layout. Not all items can be translated word by word, especially into non-Ìndo-European languages.

If you see any text which remains in English even when you have checked all items, please create bug report in the issue tracker so that the developers can fix it.

#### Extensions {#extensions}
## Translating extensions {#translating-extensions}

Extensions can be translated via Weblate just like the core software.

The Wikibase extension contains lots of domain-specific concepts, with which you may not be familiar. The Wikidata may not have reconciliation service for your language. We recommend checking the [Wikidata glossary](https://www.wikidata.org/wiki/Wikidata:Glossary) to be consistent.

By default, the system tries to load the language file corresponding to the currently in-use browser language. To override this setting a new menu item ("Language Settings") has been added at the index page.
To support a new language file, the developer should add a corresponding entry to the dropdown menu in this file: `/OpenRefine/main/webapp/modules/core/scripts/index/lang-settings-ui.html`. The entry should look like:
```javascript
<option value="<locale>">[Language Label]</option>
```
The Wikibase extension contains lots of domain-specific concepts, with which you may not be familiar. Wikidata may not have a reconciliation service for your language. We recommend checking the [Wikidata glossary](https://www.wikidata.org/wiki/Wikidata:Glossary) to be consistent.

## Server-side localisation {#server--backend-coding}
## Developer documentation {#developer-documentation}

Certain areas of the back-end can also be localized, also via Weblate.
The translated strings are stored in `.properties` file, from which Java classes are generated at compilation time.
For instance, operation descriptions are stored under [`main/resources/com/google/refine/operations`](https://github.com/OpenRefine/OpenRefine/tree/master/main/resources/com/google/refine/operations/).
If you are a developer adding new strings or a new language to OpenRefine, see the [developer guide to localization](developer-guide-to-localization).
7 changes: 0 additions & 7 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ module.exports = {
'technical-reference/code-contributions',
'technical-reference/build-test-run',
'technical-reference/functional-tests',
'technical-reference/developer-guide-to-localization',
{
type: 'category',
label: 'Architecture',
Expand Down