Migrating older extensions
Migrating from Ant to Maven
Why are we doing this change?
Ant is a fairly old (antique?) build system that does not incorporate any dependency management. By migrating to Maven we are making it easier for developers to extend OpenRefine with new libraries, and stop having to ship dozens of .jar files in the repository. Using the Maven repository also encourages developers to add dependencies to released versions of libraries instead of custom snapshots that are hard to update.
When was this change made?
The migration was done between 3.0 and 3.1-beta with this commit: https://github.com/OpenRefine/OpenRefine/commit/47323a9e750a3bc9d43af606006b5eb20ca397b8
How to migrate an extension
You will need to write a pom.xml
in the root folder of your extension to configure the compilation process with Maven. Sample pom.xml
files for extensions can be found in the extensions that are shipped with OpenRefine (gdata
, database
, jython
, pc-axis
and wikidata
). A sample extension (sample
) is also provided, with a minimal build file.
For any library that your extension depends on, you should try to find a matching artifact in the Maven Central repository. If you can find such an artifact, delete the .jar
file from your extension and add the dependency in your pom.xml
file. If you cannot find such an artifact, it is still possible to incorporate your own .jar
file using maven-install-plugin
that you can configure in your pom.xml
file as follows:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-install-plugin</artifactId>
<version>2.5.2</version>
<executions>
<execution>
<id>install-wdtk-datamodel</id>
<phase>process-resources</phase>
<configuration>
<file>${basedir}/lib/my-proprietary-library.jar</file>
<repositoryLayout>default</repositoryLayout>
<groupId>com.my.company</groupId>
<artifactId>my-library</artifactId>
<version>0.5.3-SNAPSHOT</version>
<packaging>jar</packaging>
<generatePom>true</generatePom>
</configuration>
<goals>
<goal>install-file</goal>
</goals>
</execution>
<!-- if you need to add more than one jar, add more execution blocks here -->
</executions>
</plugin>
And add the dependency to the <dependencies>
section as usual:
Migrating to Wikimedia's i18n jQuery plugin
Why are we doing this change?
This adds various important localization features, such as the ability to handle plurals or interpolation. This also restores the language fallback (displaying strings in English if they are not available in the target language) which did not work with the previous set up.
When was the migration made?
The migration was made between 3.1-beta and 3.1, with this commit: https://github.com/OpenRefine/OpenRefine/commit/22322bd0272e99869ab8381b1f28696cc7a26721
How to migrate an extension
You will need to update your translation files, merging nested objets in one global object, concatenating keys. You can do this by running the following Python script on all your JSON translation files:
import json import sys
with open(sys.argv[1], 'r') as f: j = json.loads(f.read())
result = def translate(obj, path): res = if type(obj) == str: result['/'.join(path)] = obj else: for k, v in obj.items(): new_path = path + [k] translate(v, new_path)
translate(j, [])
with open(sys.argv[1], 'w') as f: f.write(json.dumps(result, ensure_ascii=False, indent=4))
Then your javascript files which retrieve the translated strings should be updated: $.i18n._('core-dialogs')['cancel']
becomes $.i18n('core-dialogs/cancel')
. You can do this with the following sed
script:
sed -i "s/$.i18n.(['"]([A-Za-z0-9/\-])['"])[['"]([A-Za-z0-9-_])["']]/$.i18n('\1/\2')/g" my_javascript_file.js
You can then chase down the places where you are concatenating translated strings, and replace that with more flexible patterns using the plugin's features.