grunt-i18n-abide

Grunt plugin for running jsxgettext against your codebase.

grunt-i18n-abide

Grunt plugin for running jsxgettext and gettext tools against your codebase. jsxgettext extracts strings from your JS and template files (EJS/Jinja (nunjucks)) to a pot format.

Version 0.0.20 of i18n-abide has changed how it handles locales with script subtags. E.g. sr_LATN now becomes sr_Latn. In other words locales with script subtags are now formatted so the initial character of the subtag is capitalized and the remainder is lower-case. If you're using i18n-abide >= 0.0.20 rename any locales from xx_XXXX to xx_Xxxx. If you're using 0.0.20 of i18n-abide you should also upgrade to grunt-i18n-abide >= 0.0.11.

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-i18n-abide --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-i18n-abide');
  • abideExtract
  • abideCreate
  • abideMerge
  • abideCompile

In your project's Gruntfile, add a section named abideExtract to the data object passed into grunt.initConfig().

This example show two targets for extracting strings from JS and HTML. They both use the same destination.

  abideExtract: {
    js: {
      src: 'lib/**/*.js',
      dest: 'locale/templates/LC_MESSAGES/messages.pot',
      options: {
        language: 'JavaScript',
      }
    },
    html: {
      src: 'templates/**/*.html',
      dest: 'locale/templates/LC_MESSAGES/messages.pot',
      options: {
        language: 'Jinja',
      }
    },
  }

Standard grunt files src config allowing a set of paths to make up the list of files that are searched for gettext strings.

Standard grunt files dest config allowing configuration of where the pot file should be created.

Default value: locale/templates/LC\_MESSAGES/messages.pot

Type: Boolean Default value: true

Join messages that already exist.

Type: String

A way to specify what gettext function you are using e.g. '_' for _('Translate this')

Type: String Default value: 'JavaScript'

A string value to tell jsxgettext what type of code you are extracting strings from.

In your project's Gruntfile, add a section named abideCreate to the data object passed into grunt.initConfig().

  abideCreate: {
    default: { // Target name. 
      options: {
        template: 'locale/templates/LC_MESSAGES/messages.pot', // (default: 'locale/templates/LC_MESSAGES/messages.pot') 
        languages: ['en-US', 'fr', 'es'],
        localeDir: 'locale',
      }
    }
  },

Type: String Default value: locale/templates/LC\_MESSAGES/messages.pot

The path to the template pot file strings are extracted to.

Type: Array

A list of the language codes you want to create locales for e.g. en-US not en_US.

Type: String Default value: locale

The base locale directory.

In your project's Gruntfile, add a section named abideMerge to the data object passed into grunt.initConfig().

This command merges newly extracted strings into the locales.

  abideMerge: {
    default: { // Target name. 
      options: {
        template: 'locale/templates/LC_MESSAGES/messages.pot', // (default: 'locale/templates/LC_MESSAGES/messages.pot') 
        localeDir: 'locale',
      }
    }
  },

Type: String Default value: locale/templates/LC\_MESSAGES/messages.pot

The path to the template pot file strings are extracted to.

Type: String Default value: locale

The base locale directory.

In your project's Gruntfile, add a section named abideCompile to the data object passed into grunt.initConfig().

This command can take multiple targets, so you can compile more than one set of files if you want or a mix of mo/JSON.

  abideCompile: {
    json: {
      dest: '/json/',
      options: {
        type: 'json',
        localeDir: 'tests/tmp',
      }
    },
    mo: {
      options: {
        type: 'mo',
        localeDir: 'tests/tmp',
      }
    }
  },

Standard grunt files dest config allowing configuration of where the json should end up.

Type: String

The type of compilation mo or json

Type: Boolean Default value: true

Only relevant when options.type is set to 'json'. If false the JS files won't be created alongside the json. If you don't need the js e.g. you're not producing a client-side app that uses the JS then set this to false.

Type: String Default value: json_locale_data

Allows you to override the JS var used in the JS output. The var is added to the window object. So by default you'll end up with window.json_locale_data. This value is crudely validated to help ensure you don't use a reserved word or an invalid property name.

Type: String Default value: locale

The base locale directory.

Type: String Default value: grunt-i18n-abide.lock

An option to customise the lockfile name.

This can be useful if you might be running multiple builds concurrently on the same server. Set this to use an environment variable or use a grunt cli option so each job has a unique lockfile name.

grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
 
  abideCreate: {
    default: { // Target name.
      options: {
        template: 'locale/templates/LC_MESSAGES/messages.pot', // (default: 'locale/templates/LC_MESSAGES/messages.pot')
        languages: ['en-US', 'fr', 'es'],
        localeDir: 'locale',
      }
    }
  },
  abideExtract: {
    js: {
      src: 'lib/**/*.js',
      dest: 'locale/templates/LC_MESSAGES/messages.pot',
      options: {
        language: 'JavaScript',
      }
    },
    html: {
      src: 'templates/payments/*.html',
      dest: 'locale/templates/LC_MESSAGES/messages.pot',
      options: {
        language: 'Jinja',
      }
    },
  },
  abideMerge: {
    default: { // Target name.
      options: {
        template: 'locale/templates/LC_MESSAGES/messages.pot', // (default: 'locale/templates/LC_MESSAGES/messages.pot')
        localeDir: 'locale',
      }
    }
  },
  abideCompile: {
    json: {
      dest: 'media/locale/',
      options: {
        type: 'json',
        createJSFiles: false, // defaults to true
      }
    },
    mo: {
      options: {
        type: 'mo',
      }
    }
  },
});

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Bear in mind this code only wraps jsxgettext and standard gettext tools. If there's a problem with how grunt talks to jsxgettext or those CLI tools then that's a problem with this package. However if the output is not correct (and it's not related to configuration) please file a bug on the relevant project.

  • 0.0.14
    • Use shell.which() to determine the path to commands.
  • 0.0.13
    • Allow custom lockfile name for abideCompile
    • .po names are based on template name in abideCreate (thanks @andreas-marschke)
    • Update i18n-abide 0.0.20 -> 0.0.22
    • Update po2json 0.2.3 -> 0.3.2
    • Update jsxgettext 0.4.3 -> 0.5.3
  • 0.0.12
    • Fix lockfile path on windows (thanks @harcogijsbers)
  • 0.0.11
    • Update i18n-abide 0.0.19 -> 0.0.20
  • 0.0.10:
    • Use localeFrom and languageFrom from i18n-abide.
    • Update jsxgettext 0.4.0 -> 0.4.2
    • Update i18n-abide 0.0.17 -> 0.0.19
    • Update shelljs 0.2.6 -> 0.3.0
    • Update dev deps.
  • 0.0.9:
    • Use pretty json for readability.
  • 0.0.8:
    • Provide configuration for jsVar in js output.
    • Output lang/locale for js output.
    • Update po2json + jsxgettext.
  • 0.0.7:
    • Fix bug if createJSFiles is true.
  • 0.0.6:
    • Make abideCreate a noop if locale already exists.
    • Add createJSFiles option to abideCompile.
  • 0.0.5:
    • options.locales -> options.languages in abideCreate.
    • fix dir creation.
    • Move npm images to mozilla repo.
    • Update package.json.
  • 0.0.4:
    • Updated deps.
  • 0.0.3:
    • Updated for initial npm release.
  • 0.0.2:
    • Updates related to jsxgettext changes.
  • 0.0.1:
    • Initial version.