Missing usage documentation

[AlexSchuetz]

Hi,
since I'm no gradle expert I cannot fiqure out how to use this plugin. Can you give some basic examples?

[tschulte]

The gradle-gettext-plugin in it's current state is only a proof of concept for exactly one and one only workflow:

• Java project with .properties files (i.e. not using Gettext in the code)
• Developers edit the template .properties files (i.e. the files without language code, e.g. messages.properties)
• Translation is done with gettext
  • Task updatePot creates/updates .pot files (using prop2po)
  • Task updatePo updates _language.po files (using msgmerge, automatically called by updatePot)
  • Translation of the _language.po files using the regular GNU tools
  • Task updateProperties creates/updates the _language.properties files (using po2prop)

I.e. the developers only work with the template .properties files and the .po files. Both the _language.properties and the .pot files are generated/updated by the plugin.

Additionally a task importResourceBundles can be used to initially import existing _language.properties.

In it's current state it does not allow to extract .pot files from Java source files.

This was created to evaluate, if the above workflow -- translating .properties files using gettext -- is viable.

You are most probably searching for a plugin that supports the default GNU gettext workflow, i.e. English texts in .java files, extract these Strings using xgettext, etc.

This plugin could be altered to support that workflow. It could even be changed to support both the above and the real GNU gettext workflow. But on the other hand, gradle allows -- other than maven -- to easily create tasks for everything. E.g.

task xgettext(type: Exec) {
    def outputFile = file("src/main/i18n/keys.pot")

    // to enable UP-TO-DATE checks
    outputs.file outputFile
    inputs.files sourceSets.main.java

    // ensure the folder exists
    doFirst {
        outputFile.parentFile.mkdirs()
    }

    // delegate to xgettext
    executable "xgettext"
    args "--from-code=utf-8"
    args "--output=$outputFile"
    args "--language=java"
    args "--sort-output"
    fileTree('src/main/java') {
        include '**/*.java'
    }.each {
        args it
    }
}

would call xgettext. Maybe that's the reason there is no gradle-gettext-plugin available yet. And since ant is a first class gradle citizen, it is even possible to use existing ant tasks (if there are any?).

If you want, we can further discuss, if and how we could bring this plugin into better shape.

[AlexSchuetz]

Thank's for your detailed answer. Indeed I am looking for a plugin to support the default gettext workflow, but your workflow is also very interesting, although I don't like translation tokens which are commonly used for message.properties.

Currently I am using gettext-maven-plugin which is available via maven central. There are a few libraries, that have to be translated and in the servlet-application I use maven to extract those libraries and scan them with custom keywords. Finally I have some test-methods to check that none of the translations is fuzzy or incomplete with JUnit.

It would be nice to do add this functionality to this plugin and I would like to participate on it. But unfortunately I am no gradle expert right now and definitly no gradle-plugin-developer. I'll fork this repo and try to implement the normal gettext workflow. This may take some time.
As I proceed we can discuss what the plugin configuration could look like.

[tschulte]

Excellent! I'd love to work with you on this. We should first define the workflow(s) to be supported. I do not have any real experience with the default gettext workflow. From what I know -- and your use case seems to be the same -- the default is to generate one .pot file for the whole application. But one .pot file for each .jar file might also be a use case? Or even multiple .pot files (e.g. one for each dialog)?

AFAIK there is not the one GNU gettext workflow. Some people generate a keys.pot and than have a de.po, fr.po, etc. others generate a msg.pot and have msg_de.po, msg_fr.po. But maybe we should first implement the most common workflow and define that as the default. So when later adding more options, existing users of the plugin don't break.

As a starting point to learn Gradle plugin development, you can have a look at https://docs.gradle.org/current/userguide/custom_plugins.html and https://guides.gradle.org/designing-gradle-plugins/.

If you have any questions, feel free to ask. You can also send me an email (see my commits for he email address).

[AlexSchuetz]

I was thinking about one pot-file for each library as well. Indeed this was my initial design, but there have been a lot of difficulties with it (class/resource bundle loading). Then I switched to one application pot-file which extremely simplifies things. For the workflow: We should keep it generic as long as possible. If we provide a set of configurable tasks that should be sufficient. I think ideal would be a task to scan (xgettext and existing property files) which generates/updates the pot file. A second task to merge pot files with corresponding po files. And finally a task to process po-files into classes or properties. Options should at least include ways to define what to scan, where to scan, where to put the results and what the results should be named like. Things like extracting library sources for scanning should not be part of the plugin right now. (Although this would be great for my workflow ;) ) I think we should define an extension, where you can define something like flavours and the tasks get executed for each flavour? Since I am not experienced with Gradle at all, it is hard for my to imagine what the configuration should look like, since I am not aware of all consequences.

[tschulte]

Yes, that sounds reasonable. A set of tasks, that could be used manually. Plus a plugin and extension with defaults. Maybe even multiple plugins or a base plugin and specialized plugins (like the java-base and java plugins in gradle).

Since multiple tasks will share the same settings, using the plugin and extension will allow to only define these once.

Normally the plugin will create the tasks and the extension. The extension will populate the tasks or alternatively the tasks will retrieve their options from the extension. Another option might be to use the new incubating software model. But I have not done anything with that yet.

[AlexSchuetz]

Just thinking loudly: Is it possible, that the tasks get created and populated by the extension at execution time? Or would this happen in the config phase? I think the po-processing should always be executed (since the generated files shouldn't be committed to any scm). The extraction and merging can be simplified into one explicit task. Is it possible to ensure, that the po-processing takes place after this task in any way? I think I'll have to start working on it, to get to know Gradle... Unfortunately this won't be possible this week...

[tschulte]

No, AFAIK tasks must be created at config phase. But they can be populated, i.e. the params be set by the extension. Normally this would also be at configuration time.

It is possible to define finalizedBy dependencies. If you have a look at the GradleGettextPlugin in it's current form:

        def updatePropertiesTask = project.tasks.create('updateProperties', UpdatePropertiesTask) {
            [...]
        }
        def updatePoTask = project.tasks.create('updatePo', UpdatePoTask) {
            finalizedBy updatePropertiesTask
            [...]
        }
        def updatePotTask = project.tasks.create('updatePot', UpdatePotFromPropertiesTask) {
            finalizedBy updatePoTask
            [...]
        }

updatePot creates the pot files, after that, updatePo is automatically called, and after that updateProperties is automatically called. Have a look at https://docs.gradle.org/current/userguide/more_about_tasks.html#sec:adding_dependencies_to_tasks

[evgeniykarpenko]

Can you please explain how to use this plugin in the Android Studio project?
From the beginning, how to connect it.
If i add this
`

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath 'de.gliderpilot.gradle.gettext:gradle-gettext-plugin:+'
    }
}

apply plugin: 'de.gliderpilot.gettext`

I get an error:

What's wrong ?
Thank you.

[tschulte]

I have never released any version of this plugin. Therefore you'll have to build it yourself:

./gradlew pTML would execute the publishToMavenLocal task and publish to your .m2/repository folder.

To use the plugin you would need to use mavenLocal() instead of jcenter().