{"id":20357881,"url":"https://github.com/gandi/react-translate","last_synced_at":"2025-04-12T03:15:13.801Z","repository":{"id":66736709,"uuid":"74043696","full_name":"Gandi/react-translate","owner":"Gandi","description":"I18N libraries and tools for your react application.","archived":false,"fork":false,"pushed_at":"2018-10-11T07:27:28.000Z","size":84,"stargazers_count":13,"open_issues_count":1,"forks_count":4,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-12T03:15:08.657Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@gandi/react-translate","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gandi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-17T16:06:11.000Z","updated_at":"2023-06-13T14:32:52.000Z","dependencies_parsed_at":"2023-03-27T12:32:33.207Z","dependency_job_id":null,"html_url":"https://github.com/Gandi/react-translate","commit_stats":{"total_commits":36,"total_committers":10,"mean_commits":3.6,"dds":0.5277777777777778,"last_synced_commit":"17f376a71883141fab87b3c9a0ce71ce6b958842"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Freact-translate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Freact-translate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Freact-translate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gandi%2Freact-translate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gandi","download_url":"https://codeload.github.com/Gandi/react-translate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248510001,"owners_count":21116130,"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-14T23:24:19.380Z","updated_at":"2025-04-12T03:15:13.795Z","avatar_url":"https://github.com/Gandi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"**// DEPRECATED: please consider to use [linguijs](https://lingui.js.org/) or other alternatives.**\n\n# @gandi/react-translate\n\n\u003eI18N libraries and tools for your react application.\n\n[![build status](https://img.shields.io/travis/Gandi/react-translate/master.svg?style=flat-square)](https://travis-ci.org/Gandi/react-translate)\n[![npm version](https://img.shields.io/npm/v/@gandi/react-translate.svg?style=flat-square)](https://www.npmjs.com/package/@gandi/react-translate)\n[![npm downloads](https://img.shields.io/npm/dm/@gandi/react-translate.svg?style=flat-square)](https://www.npmjs.com/package/@gandi/react-translate)\n[![#gandi on freenode](https://img.shields.io/badge/irc-%23gandi%20%40%20freenode-61DAFB.svg?style=flat-square)](https://webchat.freenode.net/)\n\n**Features:**\n\n* String localization with [counterpart](https://github.com/martinandert/counterpart);\n* Messages extraction;\n* Catalogs management (similar to [gettext](https://en.wikipedia.org/wiki/Gettext));\n* Date \u0026 Time formats with [momentjs](http://momentjs.com/);\n* Prices and number format with [intljs](https://github.com/andyearnshaw/Intl.js);\n* Several components \u0026 functions.\n\n## Installation\n\n```\nnpm install --save @gandi/react-translate\n```\n\nAdd the following script to your `package.json`, it's a simple shortcut for extraction\nscripts:\n\n```\n// ...\n\"scripts\": {\n  // ...\n  \"i18n\": \"react-translate-scripts\"\n}\n```\n\nExtraction script requires `babel-cli`, `babel-gettext-plugin` and `po2json` in your dependencies\n(it's up to you to select the version saved in your project):\n\n```\nnpm install --save-dev babel-cli babel-gettext-plugin po2json\n```\n\n## Usage\n\n### 1. init: `provideTranslate`\n\nProvide some helpers functions in the React context.\n\nIt's up to you to load `translations` from the json generated by scripts (cf.\n[How to create language files]). So you will be able to promise a json object or preload translations\ndirectly in the DOM (e.g. via server side rendering).\n\n```javascript\nimport { provideTranslate, createTranslator } from '@gandi/react-translate';\n\nconst translatorParams = {\n  translations: {       // catalog\n    'This is a test %(username)s!': 'C\\'est un test %(username)s!',\n  },\n  locale: 'fr',         // user's locale\n  utcOffset: 0,         // user's zone offset\n  defaultLocale: 'en',  // default application locale\n  logMissing: false,    // display warnings when translations are missing (except on production)\n  localeData: {         // IntlPolyfill localeData configuration\n    locale: 'fr',\n    number: {\n      currencies: {\n        USD: '$US',\n        EUR: '€',\n      },\n    },\n  },\n};\n\nconst translator = createTranslator(translatorParams);\n\n@provideTranslate(translator)\nclass App {\n  render() {\n    ...\n  }\n}\n```\n\n### 2. Implementation: `withTranslator(options)`\n\nInject helpers into the components props from context variables.\n\n```javascript\nimport React, { Component, PropTypes } from 'react';\nimport { withTranslator } from '@gandi/react-translate';\n\n@withTranslator()\nclass MyComponent extends Component {\n  static propTypes = {\n    __: PropTypes.func.isRequired,\n  };\n\n  static preFetch({ __ }) {\n    console.log(__('So i18n'));\n  }\n\n  render() {\n    const { __ } = this.props;\n    return (\u003cdiv\u003e{ __('So i18n') }\u003c/div\u003e);\n  }\n}\n```\n\nIn order to prevent the [unknown props warning](https://facebook.github.io/react/warnings/unknown-prop.html)\n(and non-standard DOM attributes):\n\n```javascript\nbundle.js:2009 Warning: Unknown props `formatDate`, `formatNumber`, `formatPrice`, `formatCurrency`, `localize`\non \u003cbutton\u003e tag. Remove these props from the element. For details, see https://fb.me/react-unknown-prop\n```\n\nyou can use the `propsNamespace` option:\n\n```javascript\n@withTranslator({ propsNamespace: 'translator' })\nclass Presenter extends React.Component {\n  static propTypes = {\n    translator: PropTypes.shape({ __: PropTypes.func.isRequired }),\n  };\n\n  render() {\n    const { translator: { __ }, ...props } = this.props;\n\n    return \u003cButton {...props}\u003e{__('foobar')}\u003c/Button\u003e;\n  }\n}\n```\n\n## 3. Create language files\n\nThis library uses babel and the plugin\n[babel-gettext-plugin](https://www.npmjs.com/package/babel-gettext-plugin) to extract your\ninternationalized strings.\n\n\u003e In case you created your app with create-react-app you have to declare the babel preset you need\nto build your application, for example:\n\n```json\n// file:.babelrc\n{\n  \"presets\": [\"react\"]\n}\n```\n\n### Message files\n\nFirst create a template message file with all the translation strings in a json:\n\n```bash\nnpm run i18n extract_messages [folder/to/extract] [namespace]\n```\n\n_(All commands are launched from the root directory of your node project.)_\n\n### Catalogs\n\nA catalog file is a json file, representing a single language.\n\nBefore the first run you'll need to create one folder per needed locale, for instance:\n\n```bash\nmkdir locales/{fr,it,es}\n```\n\nAfter you created your message file – **and each time you make changes to it** – you’ll need to\ncreate or update the catalogs:\n\n```bash\nnpm run i18n create_catalog \u0026\u0026 npm run i18n update_catalog\n```\n\nSometimes you must clean the catalogs by running this command:\n\n```bash\nnpm run i18n clean_catalog\n```\n\n\u003e Tips: In case you use a tool like weblate, you may not clean every time you are extracting\n\u003e messages or updating catalogs to avoid losing old translations that could be used by the tool to\n\u003e suggest translations.\n\n## Documentation\n\n* [Translator (aka `__`)](doc/translator.md)\n* [Date/Time (aka `localize`)](doc/localize.md)\n* [Pricing (aka prize)](doc/prize.md)\n* [formatCurrency (aka MapCurrencyISOToSymbol)](doc/formatCurrency.md)\n* [Number formatting (aka formatNumber)](doc/formatNumber.md)\n\n## Tests\n\nMore in [testing documentation](doc/testing.md).\n\nYou have various ways to stub your translator.\n\n```javascript\nimport { createTranslateContext, createTranslateContextTypes }\n  from '@gandi/react-translate/dist/test';\n\ndescribe('...', () =\u003e {\n  it('...', () =\u003e {\n    const wrapper =  mount(\u003cComponent /\u003e, {\n      context: createTranslateContext(),\n      childContextTypes: createTranslateContextTypes(),\n    });\n  });\n});\n```\n\n```javascript\nimport { stubProvideTranslate } from '@gandi/react-translate/dist/test';\n\ndescribe('LocalLoader component', () =\u003e {\n  it('should render a spinner', () =\u003e {\n    const LocalLoader_ = stubProvideTranslate({ locale: 'fr' })(LocalLoader);\n    // ...\n  });\n});\n```\n\n## Components examples\n\n`@gandi/react-translate` comes bundled wit some components:\n\n```jsx\n\u003cdiv\u003e\n  \u003cDateTime\u003e1982-03-28 12:00:00 UTC\u003c/DateTime\u003e\n  \u003cFromNow\u003e1982-03-28 12:00:00 UTC\u003c/FromNow\u003e\n\u003c/div\u003e\n```\n\nTo use localization programmatically, just do:\n\n```javascript\nimport React, { Component, PropTypes } from 'react';\nimport { withTranslator } from '@gandi/react-translate';\n\n@withTranslator()\nclass MyComponent extends Component {\n  static propTypes = {\n    localize: PropTypes.func.isRequired,\n  };\n\n  static preFetch({ localize }) {\n    console.log(localize(new Date()).format('LLLL'));\n  }\n\n  render() {\n    const { localize } = this.props;\n    return (\u003cdiv\u003e{ localize(new Date()).format('LLLL') }\u003c/div\u003e);\n  }\n}\n```\n\n## App samples\n\nCheck the samples/app directory to see a \"real\" application in action.\n\n```bash\ncd samples/app\nnpm i\nnpm run start\n```\n\n## Change Log\n\nAll notable changes to this project will be documented in [this section](CHANGELOG.md).\n\n*This project adheres to [Semantic Versioning](http://semver.org/) and [Keep A Changelog](http://keepachangelog.com/).*\n\n## Patrons\n\nThe work on this project was possible thanks to [Gandi.net](https://gandi.net) (#no_bullshit).\n\n## Found a bug or contribute?\n\nPlease open an [issue](https://github.com/Gandi/react-translate/issues). If it's clear and well\nlabelized, it's quicker to fix!\n\nElse you can start with [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## TODO\n\n* Document `Pricing` features\n* Add formatCurrency component\n* Improve doc on how to load translations (at least give an example)\n* Link translator options to related libs\n* Allow user to init a logger for missing translations and use `warning` as fallback\n* Fix or change build process in `bin/merge_catalogs` which looks for legacy gandi's catalogs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgandi%2Freact-translate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgandi%2Freact-translate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgandi%2Freact-translate/lists"}