Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Zhao Xiaojie Update status of localization 8020e69 May 10, 2019
2 contributors

Users who have contributed to this file

@LinuxSuRen @bitwiseman
161 lines (113 sloc) 6.51 KB

JEP-216: Localization Plugin

Abstract

Localization plugins separate i10n resource files from Jenkins core and plugins. This solution provides a way to let more native speakers contribute localization resouces more efficiently. Also for a single Jenkins running instance does not need to load all languages files in most cases.

Specification

For this proposal, each language has single localization plugin, such as Chinese Localization plugin.

All language plugins will have share a consistent directory structure. This guide describes the set of conventions to be followed when contributing to any language plugin.

Like other Maven projects, we have the directory src. All localization files that come from the Jenkins core should be in under src/core directory. For the numbers of plugins, their localization files will be placed in src/plugins. You can find the details about this from the prototype implementation.

Creating a Plugin

Plugin Naming

Localization plugin naming convention: localization-[language code]-[conuntry code]-plugin. You could add more hunman-readable descriptions in the pom.xml file. For example, <name>Localization: Chinese (Simplified)</name>.

Dependencies

You should add Localization Support Plugin as a dependency. Please don’t add more dependencies unless absolutely required. We need to keep the localization plugins as simple as possible. There’s an extension point(LocalizationContributor) that must to implemented. Only one language is allowed per localization plugin. However, you can add multiple variants of one language to single localization plugin, if the contributors agree to it.

What resources need translating?

Each localization plugin should provide translations for the following items:

  • Jelly/Groovy views

  • Java source code

  • Help files

  • JavaScript files

Access Control

The quality of the localization plugin for each language is very important. Jenkins core contributors should have the full control of it. If there is a localization SIG for a particular language, the leader should have the permission too. Other contributors who wish to take the initiative to create or maintain a localization plugin can make a request to the Jenkins developers mailling list.

Motivation

Previously all language files were aggregated in one place for core and for each plugin. For example, see https://github.com/jenkinsci/jenkins/tree/master/core/src/main/resources/lib/layout In that design, when someone might want to contribute localization, but not have the permission to commit. The same could be said for people perhaps who willing to review submissions. This could make progress very slow.

Localization plugins address those limitation by putting each language into a separate plugin in its own repository. This lets native speakers own the permission, submission and review process for their plugin, speeding the improvement of native language UI experience and make Jenkins easier to use in all languages.

Reasoning

One Global Localization plugin or One per language

Having one global localization plugin might be simpler in some ways. However, it doesn’t resolve the problem of many native speakers not having needed permissions. Many other projects have separate language packs. We think that creating one plugin per language is a better solution.

Backwards Compatibility

All existing language files will be retained until a localization plugin is created for the target language and all files have been moved.

In order to keep the best installation experience, all localization files for Install Wizard will be kept in Jenkins Core. Further, all language localization plugins will be present in the language category of suggested plugins.

In order to keep well compatibility between different versions, you can add a specific version directory. For example, there is a help text for a button in ver 1.0, but it has a totally different meaning in ver 2.0. In this case, you can create two directories to store translation files. The language plugin should choose the right language files by the current version. Actually, the language plugin should always try to find current version language files first, if it doesn’t exist then use the latest one. Maybe in most of the case, we just need to maintain the latest version.

There are some issues could arise in the progress of translation, such as wrong or stale translations. For help files, we should provide a way to switch two versions between English and specific language.

In a common situation, we keep the latest version for translation in the localization plugin. But it’s necessary to keep different versions in the plugin. And the plugin should provide a way to switch them.

Mininum support Jenkins core version is 2.173.

Security

There are no security risks related to this proposal.

Infrastructure Requirements

There are no new infrastructure requirements related to this proposal.

Testing

Add junit test case to make sure that only specific language files can be placed in a specific plugin. For example, all files should contain zh-cn in localization-zh-cn-plugin. Automated testing in this area would be extremely time consuming. We will depend on plugin mantainers and contributors to review all changes for quality, including manual testing.

You can’t perform that action at this time.