Migration Between Plugin Versions

You might want to modify messages in different versions of your plugin. This is a common problem, since you must decide which parts of your messages files to refresh and which to leave untouched. After all, you don't want to override parts of the files that administrators might have modified to please their usage case already.

Generally, when calling translator.saveLocale(locale), modified files will not be touched at all. Only if dictionary values are present for messages at runtime but not in file, they will be written to file. This might be the case if the administrator deleted lines or files of his bundle.

To explicitly write lines into your files, use

translations.saveMessagesAndBackupExistingValues(myMessagesThatHaveChangedSinceLastVersion);

Notice that this method should only be called whenever you update between two versions. You would therefore want to call this method in combination with a migration library like Flyway.

The method will store the existing values in the comment of the message. See the following example.

# Some comments here
my_message = Message wis a spello

# Some comments here
# Backed up value: "Message wis a spello"
my_message = Message with a spello

If you call the method n times, it will backup the old value n times accordingly if it differs. Comments might grow accordingly.