{"id":20277334,"url":"https://github.com/bitjson/gulp-l10n","last_synced_at":"2025-04-11T05:43:26.637Z","repository":{"id":27858827,"uuid":"31349477","full_name":"bitjson/gulp-l10n","owner":"bitjson","description":"A gulp plugin for localizing html.","archived":false,"fork":false,"pushed_at":"2016-11-11T16:52:58.000Z","size":66,"stargazers_count":14,"open_issues_count":15,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-25T03:42:01.915Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/gulp-l10n","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitjson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-26T03:48:21.000Z","updated_at":"2020-06-24T09:16:41.000Z","dependencies_parsed_at":"2022-08-25T21:23:46.576Z","dependency_job_id":null,"html_url":"https://github.com/bitjson/gulp-l10n","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fgulp-l10n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fgulp-l10n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fgulp-l10n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fgulp-l10n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitjson","download_url":"https://codeload.github.com/bitjson/gulp-l10n/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247968375,"owners_count":21025823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T13:17:59.925Z","updated_at":"2025-04-11T05:43:26.612Z","avatar_url":"https://github.com/bitjson.png","language":"JavaScript","readme":"[![npm version](https://badge.fury.io/js/gulp-l10n.svg)](https://www.npmjs.com/package/gulp-l10n) [![Build Status](https://travis-ci.org/bitjson/gulp-l10n.svg)](https://travis-ci.org/bitjson/gulp-l10n) [![Coverage Status](https://coveralls.io/repos/bitjson/gulp-l10n/badge.svg?branch=master)](https://coveralls.io/r/bitjson/gulp-l10n?branch=master) [![Dependency Status](https://david-dm.org/bitjson/gulp-l10n.svg)](https://david-dm.org/bitjson/gulp-l10n) [![Stories in Ready](https://badge.waffle.io/bitjson/gulp-l10n.png?label=ready\u0026title=Ready)](https://waffle.io/bitjson/gulp-l10n)\n\n# gulp-l10n\nA gulp plugin that wraps [s18n](https://github.com/bitjson/s18n) and provides simple tooling for localizing html. Perfect for static generated sites and applications.\n\nBy default, this plugin generates localized html files and outputs them to a subdirectory for each locale, a popular pattern for localizing web content. For example: when `example.com/about` is localized with the `de` locale, it is placed at `example.com/de/about`.\n\n# Usage\n\n```js\nvar gulp = require('gulp');\nvar l10n = require('gulp-l10n');\n\n// Prior to localization, pipe your locales to the setLocales method\n\ngulp.task('load-locales', function () {\n  return gulp.src('locales/*.json')\n    .pipe(l10n.setLocales());\n});\n\n// Files piped to the plugin are localized and cloned to a separate subdirectory\n// for each locale. e.g.: 'index.html' \u003e 'de/index.html'\n\ngulp.task('localize', ['load-locales'], function () {\n  return gulp.src('src/**/*.html')\n    .pipe(l10n())\n    .pipe(gulp.dest('dist'))\n});\n\ngulp.task('default', ['localize']);\n```\n\n## Extracting Locales for Translation\nThe Extract method accepts an `s18n extract` options object. See [s18n's extract options](https://github.com/bitjson/s18n#extract-options) for full documentation and defaults.\n\n```js\nvar gulp = require('gulp');\nvar l10n = require('gulp-l10n');\n\nvar opts = {\n  elements: ['title', 'p', 'h1'],\n  attributes: ['alt', 'title'],\n  directives: 'translate=yes',\n  attributeSetter: 'translate-attrs'\n};\n\ngulp.task('extract-locales', function () {\n  return gulp.src('src/**/*.html')\n    .pipe(l10n.extract(opts))\n    .pipe(gulp.dest('locales'));\n});\n```\n\n### Continuous Localization\nTo automatically extract new strings for translation, simply add your locale extraction task to your build process.\n\n```js\nvar gulp = require('gulp');\nvar l10n = require('gulp-l10n');\n\ngulp.task('extract-locales', function () {\n  return gulp.src('app/**/*.html')\n    .pipe(l10n.extract())\n    .pipe(gulp.dest('locales'));\n});\n\ngulp.task('load-locales', ['extract-locales'], function () {\n  return gulp.src('locales/*.json')\n    .pipe(l10n.setLocales());\n});\n\ngulp.task('localize', ['load-locales'], function () {\n  return gulp.src('app/**/*.html')\n    .pipe(l10n())\n    .pipe(gulp.dest('dist'));\n});\n\ngulp.task('prepare', ['extract-locales']);\ngulp.task('default', ['localize']);\n```\n\n### Enforcing Localization\nThe enforce option of the `setLocales` method provides a way to warn or error when strings are not translated. With `options.enforce` set to `warn`, when any locale is missing a string from the `native` locale, setLocales will log the problem. With `options.enforce` set to `strict`, an error will be thrown.\n\n```js\n...\n\ngulp.task('load-locales', ['extract-locales'], function () {\n  return gulp.src('locales/*.json')\n    .pipe(l10n.setLocales({\n      native: 'en',\n      enforce: 'warn'\n    }));\n});\n\n...\n```\n\n#### Example:\n`locales/en.json`:\n\n```json\n  {\n    \"37b51d19\": \"bar\",\n    \"acbd18db\": \"foo\"\n  }\n```\n\n`locales/de.json`:\n\n```json\n  {\n    \"37b51d19\": \"bår\"\n  }\n```\n\nWill warn:\n\n```bash\nWARN: locale `de` is missing: `acbd18db`, native string: `foo`\n```\n\n## Testing Localization\nTo simulate translation (for testing purposes), you can use the s18n CLI's `$ s18n map`. See s18n [Testing Localization](https://github.com/bitjson/s18n#testing-localization) for more information.\n\n## Rewriting `href`s\nThe `hrefRewrite` option accepts a function which transforms the contents of all `a` element `href` attributes in each locale. This is ideal for completely static sites, where little or no server logic is being employed to serve appropriate locales to visitors (eg: GitHub Pages). This rewriting allows users to navigate the static site within their chosen locale.\n\n```js\ngulp.task('localize', ['load-locales'], function () {\n  return gulp.src('app/**/*.html')\n    .pipe(l10n({\n      hrefRewrite: function(href, locale){\n        if(href.charAt(0) === '/'){\n          return '/' + locale + href;\n        }\n        else {\n          return href;\n        }\n      }\n    }))\n    .pipe(gulp.dest('dist'));\n});\n```\n\n### Rewriting Other URLs and Attributes\nThe `hrefRewrite` option is deliberately limited in scope to `a` element `href`s. To localize other URLs, like `image src`s, `link href`s, and other html attributes, it's recommended that [s18n](https://github.com/bitjson/s18n) Attribute Setters and Cancelers be used. This ensures all localization information is available in locale files, rather than relying upon project configuration.\n\n## Multiple Projects\nWhen localizing multiple projects with the same instance of gulp-l10n, it's possible to pass a `cacheId` option to the gulp-l10n.setLocales() and gulp-l10n() methods. The default `cacheId` is `default`.\n\n```js\nvar gulp = require('gulp');\nvar l10n = require('gulp-l10n');\n\ngulp.task('load-locales-1', function () {\n  return gulp.src('locales1/*.json')\n    .pipe(l10n.setLocales('en', {\n      cacheId: 'foo'\n    }));\n});\n\ngulp.task('localize-1', ['load-locales-1'], function () {\n  return gulp.src('src1/**/*.html')\n    .pipe(l10n({\n      cacheId: 'foo'\n    }))\n    .pipe(gulp.dest('dist/src1'));\n});\n\ngulp.task('load-locales-2', function () {\n  return gulp.src('locales2/*.json')\n    .pipe(l10n.setLocales('en', {\n      cacheId: 'bar'\n    }));\n});\n\ngulp.task('localize-2', ['load-locales-2'], function () {\n  return gulp.src('src2/**/*.html')\n    .pipe(l10n({\n      cacheId: 'bar'\n    }))\n    .pipe(gulp.dest('dist/src2'));\n});\n\ngulp.task('default', ['localize-1', 'localize-2']);\n```\n\n# API\nThe Node API as if the gulp-l10n plugin is assigned to the variable `l10n`.\n\n```js\nvar l10n = require('gulp-l10n');\n```\n\n## l10n.extract()\nPipe html files to this method to semantically extract strings for translation.\n\nThis method clears the pipe and outputs only a single native locale – by default: `en.json`.\n\n```js\n  // inside a gulp task:\n\n  var options = {\n    native: 'de',\n    elements: ['title', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'test'],\n    attributes: ['alt', 'title', 'test']\n  };\n\n  return gulp.src('**/*.html')\n    .pipe(l10n.extract( options ))\n    .pipe(gulp.dest('locales'));\n```\n\n### Options\nThe `l10n.extract()` options object accepts all [s18n extract options](https://github.com/bitjson/s18n#extract), as well as the `gulp-l10n`-specific options below.\n\n#### native\n- **Accepts**: _String_\n- **Default**: `'en'`\n\nSet the locale code in which your website or application is authored. This is used in the file name of the native locale output by the method.\n\n## l10n.setLocales()\nPipe locales through this method before piping html through l10n().\n\n```js\n  // inside a gulp task:\n\n  var options = {\n    native: 'de',\n    cacheId: 'test'\n  };\n\n  return gulp.src('locales/*.json')\n    .pipe(l10n.setLocales( options ));\n```\n\n### Options\nThe `l10n.setLocales()` method accepts an options object.\n\n#### native\n- **Accepts**: _String_\n- **Default**: `'en'`\n\nSet the s18n native locale. This is the locale in which your website or application is authored.\n\n**Default**: `'en'`\n\n#### cacheId\n- **Accepts**: _String_\n- **Default**: `'default'`\n\nSet the locale cache in which the locale is saved. Allows for multiple distinct websites or applications to be separately translated by the same instance of gulp-l10n.\n\n#### enforce\n- **Accepts**: _String_\n- **Default**: `'silent'`\n\nSet the enforcement mode.\n\nMode       | Description\n---------- | -------------------------------------\n`'silent'` | Do not enforce localization.\n`'warn'`   | Warn about missing localizations.\n`'strict'` | Throw error on missing localizations.\n\n## l10n()\nGulp plugin to localize html files using locales previously set with the setLocales method.\n\n```js\n  // inside a gulp task:\n\n  var options = {\n    cacheId: 'test',\n    hrefRewrite: function(href, locale){\n      if(href.charAt(0) === '/'){\n        return '/' + locale + href;\n      }\n      else {\n        return href;\n      }\n    }\n  };\n\n  return gulp.src('**/*.html')\n    .pipe(l10n( options ))\n    .pipe(gulp.dest('dist'));\n```\n\n### Options\nThe `l10n()` options object accepts all [s18n localization options](https://github.com/bitjson/s18n#localize), as well as the `gulp-l10n`-specific options below.\n\n#### cacheId\n- **Accepts**: _String_\n- **Default**: `'default'`\n\nSet the locale cache used in localizing html. Allows for multiple distinct websites or applications to be separately translated by the same instance of gulp-l10n.\n\n#### hrefRewrite\n- **Accepts**: _Function(`href`, `locale`)_, `null`\n- **Default**: `null`\n\nA function to transform all `href`s in each html document localized. The value of each href will be replaced by the value returned by this function. `Href`s will not be rewritten if this option is set to `null`.\n\nParameter | Description\n--------- | -----------------------------------------------------------------------------------------------------------------------------------------------------------\n`href`    | The original value of the `href` attribute currently being transformed.\n`locale`  | The locale code of the locale currently being applied to the html document. This is also the name of the current locale's directory. (Eg: `en`, `de`, etc.)\n\n#### outPath\n- **Accepts**: _Function(`base`, `path`, `localeId`)_, `string`\n- **Default**: `return path.replace(base, base + localeId + '/');`\n\nA function to compute a custom output path for localized files.\n\nExample for files of the form `index.de.html`\n\n```js\n\n  gulp.task('localize', function () {\n    return gulp.src('*.html')\n      .pipe(l10n({\n        outPath: function (base, path, localeId) {\n          return path.slice(0, -4) + localeId + \".html\";\n        }\n      }))\n      .pipe(gulp.dest(pkg.release));\n  });\n```\n\n# Contributing\nThe default Gulp task watches all files and runs tests and code coverage.\n\n```bash\n$ npm install -g gulp\n$ gulp\n```\n\n## Testing\nThis module strives to maintain passing tests with 100% coverage in every commit, and tests are run pre-commit. If you prefer, you can always skip this check with `git commit --no-verify` and squash WIP commits for pull requests later.\n\nIf you're unsure or would like help writing tests or getting to 100% coverage, please don't hesitate to open up a pull request so others can help!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitjson%2Fgulp-l10n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitjson%2Fgulp-l10n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitjson%2Fgulp-l10n/lists"}