Convert translations with native2ascii

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

Java property files provide localizations in the Jenkins project. Unfortunately, in the past they had to use ISO-8859-1 encoding, even for files that needed to represent characters outside of ISO-8859-1. Due to a risk of character set confusion when Jenkins reads the property files, Jenkins plugin tests will warn developers when existing property files include characters that are both valid UTF-8 and valid ISO-8859-1. When that ambiguity is detected, those files should be encoded to assure they are read correctly.

When such a conversion is needed, the Maven build process will frequently output a message like:

[ERROR] PropertiesTestSuite$PropertiesTest Time elapsed: 0.001 s <<< FAILURE!
java.lang.AssertionError: file:config_ja.properties is valid UTF-8 and
valid ISO-8859-1. To avoid problems when auto-detecting the encoding,
use the lowest common denominator of ASCII encoding and express
non-ASCII characters with escape sequences using a tool like
`native2ascii`.

Create a branch

In a local copy of your fork of the plugin repository create a git branch for your work with the command:

git checkout -b {task-identifier} master

Compile the plugin

Use Apache Maven to compile the plugin and run its automated tests with the command:

mvn clean verify

Confirm that the encoding warning message is displayed:

[ERROR] PropertiesTestSuite$PropertiesTest Time elapsed: 0.001 s <<< FAILURE!
java.lang.AssertionError: file:config_ja.properties is valid UTF-8 and
valid ISO-8859-1. To avoid problems when auto-detecting the encoding,
use the lowest common denominator of ASCII encoding and express
non-ASCII characters with escape sequences using a tool like
`native2ascii`.

If the warning message is not displayed and the plugin is using the most recent parent pom, then no conversion is necessary.

Convert the files with native2ascii

If the warning message is displayed, use native2ascii to convert the files. Use the specific files mentioned in the warning message in place of the …/config_ja.properties file in the sample below:

native2ascii .../config_ja.properties x
mv x .../config_ja.properties

Review the change that native2ascii performed with the command:

git diff
diff --git a/.../config_ja.properties b/.../config_ja.properties
index 83e3576..e661ac9 100644
--- a/.../config_ja.properties
+++ b/.../config_ja.properties
@@ -20,5 +20,5 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.

-# Authorize\ Strategy=権限の設定方法
+# Authorize\ Strategy=\u6a29\u9650\u306e\u8a2d\u5b9a\u65b9\u6cd5
 Authorize\ Strategy=\u6a29\u9650\u306e\u8a2d\u5b9a\u65b9\u6cd5

Compile the plugin

Use Apache Maven to compile the plugin and run its automated tests with the command:

mvn clean verify

Create a pull request

Commit that change:

git add {modified-files}
git commit -m "{task-description}"

Push the change to GitHub:

git push origin --set-upstream {task-identifier}

Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for '{task-identifier}' on GitHub by visiting:
remote: https://github.com/user/your-plugin/pull/new/{task-identifier}
remote:
To github.com:user/your-plugin.git
 * [new branch]      {task-identifier} -> {task-identifier}
Branch '{task-identifier}' tracking remote branch '{task-identifier}'.

Notice that the output of the command includes the URL, which can be used to open a pull request. Copy that URL in your web browser and submit a pull request.