-
Notifications
You must be signed in to change notification settings - Fork 5
Contributing Translations
If you're interested in contributing to Process Assertions by adding and/or maintaining a translation, this page contains all the information you need.
Process Assertions includes support for translation of messages to languages other than the default English ones. These messages are shown to developers when unit tests are run and assertions are performed. They include information about which checks are being performed and, should a test fail, provide context about what differed from the expectation of the test case so users can track down problems. For instance, if the test expects the process to be ended at a certain point and it is still running, a message will be shown that this particular process is not ended.
The messages aren't hardcoded into Process Assertions' code base, but can be loaded dynamically based on the user's preferences. If a user prefers to see messages in their own language, this is a configurable option. Of course, this only works if there is a translation for that language available.
The way Process Assertions allows for different languages is by including all of the messages to be shown in a special text file for each language. Depending on the configuration, the file for that language is read and its messages are used.
The special text files are standard Java properties files. If you're not familiar with Java, don't worry - it's just text, really. They contain a line for each message, with a key and a value. The keys are the same for each language because they identify the message that Process Assertions will show in each situation.
The value contains the specific message for that translation. It consists of fixed parts and dynamically inserted parts, indicated by parameter placeholders. For instance, the value
Asserting process instance with id {0} is active
might be shown as
Asserting process instance with id 33 is active
once Process Assertions has substituted the parameter that has {0} as its placeholder with, in this case, the id of the process instance that was created in the test case and being executed by the process engine.
Each of the values has a number of parameters that are replaced with the actual value by Process Assertions. Which parameter means what is indicated in a comment above the value for easy reference.
By this point you may be wondering what needs to be done to add a new language translation. This section dives into the details.
Contributing a translation or updating one follow the same basic flow of editing the properties files in a copy of the code base, adding them by pushing your changes to a branch of your own and creating a pull request to the main Process Assertions code. GitHub has extensive documentation on how this procedure works in their help section, so take a look at that if you feel unsure how to proceed.
Process Assertions uses the git-flow branching model, which means that the branch that is used to develop most code on is called develop and not the default master branch. After you clone the project, make sure to switch to the develop branch before you start editing, by doing:
git checkout develop
If you want to, you can create an issue in the project and assign it to yourself. This is not a requirement. In your commit comments, you can reference its number by including #xx where xx is the issue number.
If you're adding a new translation, you will need to create the properties files for that language first. Otherwise, you just edit the existing ones in the locations below. To create new files, the easiest way is to make a copy of the default English ones. Below are the locations where the files are found.
- process-assertions-api/src/main/resources/org/toxos/processassertions/messages/
- activiti/activiti-sources/src/main/resources/org/toxos/processassertions/activiti/messages/LogMessages.properties
- flowable/flowable-sources/src/main/resources/org/toxos/processassertions/flowable/messages/LogMessages.properties
The default English message files are the ones without any xx_yy ("locale") suffix, for instance LogMessages.properties. Create or edit the file for your own translation and make sure it has a logical suffix. The first part is for the language and the second is for the country variant you're submitting. There is a lot of information online on the default values for these locales that follow the ISO-639 standard.
After copying the original files, you can start translating the messages. As mentioned before, almost all of them include some placeholders for variables to be inserted. Please make sure your message includes all of the placeholders - this will help users by providing as much context as available. Also, try to have the parameters flow naturally into the sentence. Each line is proceeded by a comment that indicates which parameter means what. The first parameter is assigned number 0, the second number 1, etc.
As far as text style goes, see if the English version helps for your translation. As you can see there, the messages follow the same kind of, quite matter-of-fact, succinct style. They use the present tense. It's up to you, but beneficial to users if you follow the same style or at least have a consistent style for the whole language.
To ensure your translation is available to users of ProcessAssertions, it must also be added in the SupportedLocale enumeration, which you will find in the process-assertions-api module. This only has to be done the first time you create your translation.
The easiest way to test that your translation is complete, is to run a test of the project. To do that, you will need a Java development setup with Maven. If you're not familiar with that, it's beyond the scope of this description to go into all of the details. If you can run a Maven build, just do:
mvn clean test
A test will run through all of the languages listed in SupportedLocale and make sure there are messages available for each expected key.
To see your messages in action, you will also need a Java development setup. You can create a test case using the examples in the user guide and make sure you configure Process Assertions with your own SupportedLocale in the test setup. The tricky part is that you will need test cases that hit each case which results in a particular message. Guess what? Process Assertions has those ready for you! Therefore, it's easier to temporarily change the configured language in the tests that are already in the integration-tests modules of the project. Then, just run:
mvn clean test
Near the end of the build, you will see the messages being logged as the tests are run in the integration-tests modules. Don't forget to change the language for the integration-tests back to the default before you submit your changes :)
If there are updates to Process Assertions, new messages may be introduced. By default, the English messages will be copied to your files so you know which are the new ones. Make sure to leave contact details so you can be notified of new additions or changes.
If you need help adding or editing you translation, you can use either a tagged tweet to ToxosOrg or tag @tiesebarrell in a comment or GitHub issue.
Of course you will be credited if you want to. Credits for the translations are added to the project's README file and the guides. By default, your GitHub handle is listed. If you would like your full name, and/or Twitter handle added that is fine.
Thank you for your contribution! Gracias - dankjewel - danke - merci - tak...