• Stars
    star
    1,316
  • Rank 34,314 (Top 0.7 %)
  • Language
    JavaScript
  • Created almost 7 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Internationalize React apps. Not only for Component but also for Vanilla JS.

react-intl-universal

react-intl-universal is a React internationalization package developed by Alibaba Group.

npm npm npm

Features

  • Can be used not only in React component but also in Vanilla JS.
  • Simple. Only three main API and one optional helper.
  • Display numbers, currency, dates and times for different locales.
  • Pluralize labels in strings.
  • Support variables in message.
  • Support HTML in message.
  • Support for 150+ languages.
  • Runs in the browser and Node.js.
  • Message format is strictly implemented by ICU standards.
  • Locale data in nested JSON format are supported.
  • react-intl-universal-extract helps you generate a locale file easily.

Live Demo

Usage Trend

Why Another Internationalization Solution for React?

In case of internationalizing React apps, react-intl is one of most popular package in industry. react-intl decorate your React.Component with wrapped component which is injected internationalized message dynamically so that the locale data is able to be loaded dynamically without reloading page. The following is the example code using react-intl.

import { injectIntl } from 'react-intl';
class MyComponent extends Component {
  render() {
    const intl = this.props;
    const title = intl.formatMessage({ id: 'title' });
    return (<div>{title}</div>);
  }
};
export default injectIntl(MyComponent);

However, this approach introduces two major issues.

Firstly, Internationalizing can be applied only in view layer such as React.Component. For Vanilla JS file, there's no way to internationalize it. For example, the following snippet is general form validator used by many React.Component in our apps. We definitely will not have such code separated in different React.Component in order to internationalize the warning message. Sadly, react-intl can't be used in Vanilla JS.

export default const rules = {
  noSpace(value) {
    if (value.includes(' ')) {
      return 'Space is not allowed.';
    }
  }
};

Secondly, since your React.Component is wrapped by another class, the behavior is not as expected in many way. For example, to get the instance of React.Component, you can't use the normal way like:

class App {
  render() {
    <MyComponent ref="my"/>
  }
  getMyInstance() {
    console.log('getMyInstance', this.refs.my);
  }
}

Instead, you need to use the method getWrappedInstance() to get that.

class MyComponent {...}
export default injectIntl(MyComponent, {withRef: true});

class App {
  render() {
    <MyComponent ref="my"/>
  }
  getMyInstance() {
    console.log('getMyInstance', this.refs.my.getWrappedInstance());
  }
}

Furthermore, your React.Component's properties are not inherited in subclass since component is injected by react-intl.

Due to the problem above, we create react-intl-universal to internationalize React app using simple but powerful API.

Get Started

App Examples

Message With Variables

If the message contains variables the {variable_name} is substituted directly into the string. In the example below, there are two variables {name} and {where}, the second argument representing the variables in get method are substituted into the string.

Locale data:

{ "HELLO": "Hello, {name}. Welcome to {where}!" }

JS code:

intl.get('HELLO', { name: 'Tony', where: 'Alibaba' }) // "Hello, Tony. Welcome to Alibaba!"

Plural Form and Number Thousands Separators

Locale data:

{ "PHOTO": "You have {num, plural, =0 {no photos.} =1 {one photo.} other {# photos.}}" }

JS code:

intl.get('PHOTO', { num: 0 }); // "You have no photos."
intl.get('PHOTO', { num: 1 }); // "You have one photo."
intl.get('PHOTO', { num: 1000000 }); // "You have 1,000,000 photos."

Plural label supports standard ICU Message syntax.

Number thousands separators also varies according to the user's locale. According to this document, United States use a period to indicate the decimal place. Many other countries use a comma instead.

Display Currency

Locale data:

{ "SALE_PRICE": "The price is {price, number, USD}" }

JS code:

intl.get('SALE_PRICE', { price: 123456.78 }); // The price is $123,456.78

As mentioned, the locale data is in ICU Message format.

The syntax is {name, type, format}. Here is description:

  • name is the variable name in the message. In this case, it's price.
  • type is the type of value such as number, date, and time.
  • format is optional, and is additional information for the displaying format of the value. In this case, it's USD.

if type is number and format is omitted, the result is formatted number with thousands separators. If format is one of currency code, it will show in corresponding currency format.

Display Dates

Locale data:

{
  "SALE_START": "Sale begins {start, date}",
  "SALE_END": "Sale ends {end, date, long}"
}

JS code:

intl.get('SALE_START', {start:new Date()}); // Sale begins 4/19/2017
intl.get('SALE_END', {end:new Date()}); // Sale ends April 19, 2017

If type is date, format has the following values:

  • short shows date as shortest as possible
  • medium shows short textual representation of the month
  • long shows long textual representation of the month
  • full shows dates with the most detail

Display Times

Locale data:

{
  "COUPON": "Coupon expires at {expires, time, medium}"
}

JS code:

intl.get('COUPON', {expires:new Date()}); // Coupon expires at 6:45:44 PM

if type is time, format has the following values:

  • short shows times with hours and minutes
  • medium shows times with hours, minutes, and seconds
  • long shows times with hours, minutes, seconds, and timezone

Default Message

When the specific key does't exist in current locale, you may want to make it return a default message. Use defaultMessage method after get method. For example,

Locale data:

{ "HELLO": "Hello, {name}" }

JS code:

const name = 'Tony';
intl.get('HELLO', { name }).defaultMessage(`Hello, ${name}`); // "Hello, Tony"

Or using d for short:

const name = 'Tony';
intl.get('HELLO', { name }).d(`Hello, ${name}`); // "Hello, Tony"

And getHTML also supports default message.

const name = 'Tony';
intl.getHTML('HELLO').d(<div>Hello, {name}</div>) // React.Element with "<div>Hello, Tony</div>"

HTML Message

The get method returns string message. For HTML message, use getHTML instead. For example,

Locale data:

{ "TIP": "This is <span style='color:red'>HTML</span>" }

JS code:

intl.getHTML('TIP'); // {React.Element}

Helper

react-intl-universal provides a utility helping developer determine the user's currentLocale. As the running examples, when user select a new locale, it redirect user new location like http://localhost:3000?lang=en-US. Then, we can use intl.determineLocale to get the locale from URL. It can also support determine user's locale via cookie, localStorage, and browser default language. Refer to the APIs section for more detail.

Component Internationalization

When internationalizing a React component, you don't need to intl.init again. You could make it as peerDependency, then just load the locale data in the compoent.

APIs Definition

  /**
   * Initialize properties and load CLDR locale data according to currentLocale
   * @param {Object} options
   * @param {string} options.escapeHtml To escape html. Default value is true.
   * @param {string} options.currentLocale Current locale such as 'en-US'
   * @param {Object} options.locales App locale data like {"en-US":{"key1":"value1"},"zh-CN":{"key1":"值1"}}
   * @param {Object} options.warningHandler Ability to accumulate missing messages using third party services. See https://github.com/alibaba/react-intl-universal/releases/tag/1.11.1
   * @param {string} options.fallbackLocale Fallback locale such as 'zh-CN' to use if a key is not found in the current locale
   * @returns {Promise}
   */
  init(options)


  /**
   * Load more locales after init
   * @param {Object} locales App locale data 
   */
  load(locales)


  /**
   * Get the formatted message by key
   * @param {string} key The string representing key in locale data file
   * @param {Object} variables Variables in message
   * @returns {string} message
   */
  get(key, variables)

  /**
   * Get the formatted html message by key.
   * @param {string} key The string representing key in locale data file
   * @param {Object} variables Variables in message
   * @returns {React.Element} message
  */
  getHTML(key, options)

  /**
   * Helper: determine user's locale via URL, cookie, and browser's language.
   * You may not need this API, if you have other rules to determine user's locale.
   * @param {string} options.urlLocaleKey URL's query Key to determine locale. Example: if URL=http://localhost?lang=en-US, then set it 'lang'
   * @param {string} options.cookieLocaleKey Cookie's Key to determine locale. Example: if cookie=lang:en-US, then set it 'lang'
   * @param {string} options.localStorageLocaleKey LocalStorage's Key to determine locale such as 'lang'
   * @returns {string} determined locale such as 'en-US'
   */
  determineLocale(options)

  /**
   * Get the inital options 
   * @returns {Object} options includes currentLocale and locales
   */
  getInitOptions()

Compatibility with react-intl

As mentioned in the issue Mirror react-intl API, to make people switch their existing React projects from react-intl to react-intl-universal. We provide two compatible APIs as following.

  /**
   * As same as get(...) API
   * @param {Object} options 
   * @param {string} options.id 
   * @param {string} options.defaultMessage
   * @param {Object} variables Variables in message
   * @returns {string} message
  */
  formatMessage(options, variables)
  /**
   * As same as getHTML(...) API
   * @param {Object} options 
   * @param {string} options.id 
   * @param {React.Element} options.defaultMessage
   * @param {Object} variables Variables in message
   * @returns {React.Element} message
  */
  formatHTMLMessage(options, variables)

For example, the formatMessage API

const name = 'Tony';
intl.formatMessage({ id:'hello', defaultMessage: `Hello, ${name}`}, {name});

is equivalent to get API

const name = 'Tony';
intl.get('hello', {name}).d(`Hello, ${name}`);

And the formatHTMLMessage API

const name = 'Tony';
intl.formatHTMLMessage({ id:'hello', defaultMessage: <div>Hello</div>}, {name});

is equivalent to getHTML API

const name = 'Tony';
intl.getHTML('hello', {name}).d(<div>Hello</div>);

FAQ

1. How to Internationalize Message in Constants Object

If constants are defined outside of a React component, the message in constants.fruits may get loaded before intl.init(...). This can cause a warning to be displayed, such as react-intl-universal locales data "null" not exists.

// Wrong: the message in constants.fruits is loaded before `intl.init(...)`
const constants = {
  fruits : [
    { label: intl.get('banana'), value: 'banana' },
    { label: intl.get('apple'), value: 'apple' },
  ]
}
function MyComponent() {
  return <Select dataSource={constants.fruits} />
}

To fix this, you should call intl.init before render.

Solution 1

Make the message object as a function, and call it at render function.

const constants = {
    fruits : () => [  // as arrow function
        { label: intl.get('banana'), value: 'banana' },
        { label: intl.get('apple'), value: 'apple' },
    ]
}
function MyComponent() {
    // fruits is a function which returns message when rendering
    return <Select dataSource={constants.fruits()} />
}

Solution 2

Use getter syntax to make a function call when that property is looked up

const constants = {
  fruits: [
    {
      get label() {
        return intl.get("banana");
      },
      value: "banana",
    },
    {
      get label() {
        return intl.get("apple");
      },
      value: "apple",
    },
  ],
};
function MyComponent() {
  // When "label" property is looked up, it actually make a function call 
  return <Select dataSource={constants.fruits} />;
}

2. How to Bind Event Handlers to an Internationalized Message

const MyComp = (props) => {
  const onClick = (e) => {
    if (e.target.tagName === 'A') {
      // event handler for "A" tag in the message
    }
  };
  return (
    // Wrap the message in a container and listen for the children's events.
    <span onClick={onClick}>
      {intl.getHTML('more_detail').d(<span>Please refer to the <a>document</a> for more detail.</span>)}
    </span>
  )
}

Other Frontend Tools

License

This software is free to use under the BSD license.

More Repositories

1

arthas

Alibaba Java Diagnostic Tool Arthas/Alibaba Java诊断利器Arthas
Java
34,428
star
2

easyexcel

快速、简洁、解决大文件内存溢出的java处理Excel工具
Java
30,946
star
3

p3c

Alibaba Java Coding Guidelines pmd implements and IDE plugin
Kotlin
29,294
star
4

nacos

an easy-to-use dynamic service discovery, configuration and service management platform for building cloud native applications.
Java
28,956
star
5

canal

阿里巴巴 MySQL binlog 增量订阅&消费组件
Java
27,786
star
6

druid

阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品,为监控而生的数据库连接池
Java
27,644
star
7

spring-cloud-alibaba

Spring Cloud Alibaba provides a one-stop solution for application development for the distributed solutions of Alibaba middleware.
Java
27,254
star
8

fastjson

FASTJSON 2.0.x has been released, faster and more secure, recommend you upgrade.
Java
25,603
star
9

flutter-go

flutter 开发者帮助 APP,包含 flutter 常用 140+ 组件的demo 演示与中文文档
Dart
23,552
star
10

Sentinel

A powerful flow control component enabling reliability, resilience and monitoring for microservices. (面向云原生微服务的高可用流控防护组件)
Java
21,947
star
11

weex

A framework for building Mobile cross-platform UI
C++
18,204
star
12

ice

🚀 ice.js: The Progressive App Framework Based On React(基于 React 的渐进式应用框架)
TypeScript
17,771
star
13

DataX

DataX是阿里云DataWorks数据集成的开源版本。
Java
14,952
star
14

ARouter

💪 A framework for assisting in the renovation of Android componentization (帮助 Android App 进行组件化改造的路由框架)
Java
14,228
star
15

lowcode-engine

An enterprise-class low-code technology stack with scale-out design / 一套面向扩展设计的企业级低代码技术体系
TypeScript
13,869
star
16

hooks

A high-quality & reliable React Hooks library.
TypeScript
13,377
star
17

tengine

A distribution of Nginx with some advanced features
C
12,583
star
18

vlayout

Project vlayout is a powerfull LayoutManager extension for RecyclerView, it provides a group of layouts for RecyclerView. Make it able to handle a complicate situation when grid, list and other layouts in the same recyclerview.
Java
10,804
star
19

formily

📱🚀 🧩 Cross Device & High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3
TypeScript
10,716
star
20

COLA

🥤 COLA: Clean Object-oriented & Layered Architecture
Java
9,964
star
21

ali-dbhub

已迁移新仓库,此版本将不再维护
8,454
star
22

MNN

MNN is a blazing fast, lightweight deep learning framework, battle-tested by business-critical use cases in Alibaba
C++
8,307
star
23

atlas

A powerful Android Dynamic Component Framework.
Java
8,120
star
24

rax

🐰 Rax is a progressive framework for building universal application. https://rax.js.org
JavaScript
7,979
star
25

otter

阿里巴巴分布式数据库同步系统(解决中美异地机房)
Java
7,967
star
26

anyproxy

A fully configurable http/https proxy in NodeJS
JavaScript
7,726
star
27

fish-redux

An assembled flutter application framework.
Dart
7,341
star
28

AndFix

AndFix is a library that offer hot-fix for Android App.
C++
6,954
star
29

flutter_boost

FlutterBoost is a Flutter plugin which enables hybrid integration of Flutter for your existing native apps with minimum efforts
Dart
6,832
star
30

x-render

🚴‍♀️ 阿里 - 很易用的中后台「表单 / 表格 / 图表」解决方案
TypeScript
6,765
star
31

transmittable-thread-local

📌 TransmittableThreadLocal (TTL), the missing Java™ std lib(simple & 0-dependency) for framework/middleware, provide an enhanced InheritableThreadLocal that transmits values between threads even using thread pooling components.
Java
6,750
star
32

jvm-sandbox

Real - time non-invasive AOP framework container based on JVM
Java
6,601
star
33

BizCharts

Powerful data visualization library based on G2 and React.
TypeScript
6,066
star
34

freeline

A super fast build tool for Android, an alternative to Instant Run
Java
5,497
star
35

UltraViewPager

UltraViewPager is an extension for ViewPager to provide multiple features in a single ViewPager.
Java
5,004
star
36

jetcache

JetCache is a Java cache framework.
Java
4,774
star
37

AliSQL

AliSQL is a MySQL branch originated from Alibaba Group. Fetch document from Release Notes at bottom.
C++
4,689
star
38

AliOS-Things

面向IoT领域的、高可伸缩的物联网操作系统,可去官网了解更多信息https://www.aliyun.com/product/aliosthings
C
4,540
star
39

dexposed

dexposed enable 'god' mode for single android application.
Java
4,483
star
40

QLExpress

QLExpress is a powerful, lightweight, dynamic language for the Java platform aimed at improving developers’ productivity in different business scenes.
Java
4,361
star
41

BeeHive

🐝 BeeHive is a solution for iOS Application module programs, it absorbed the Spring Framework API service concept to avoid coupling between modules.
Objective-C
4,286
star
42

HandyJSON

A handy swift json-object serialization/deserialization library
Swift
4,185
star
43

x-deeplearning

An industrial deep learning framework for high-dimension sparse data
PureBasic
4,185
star
44

butterfly

🦋Butterfly,A JavaScript/React/Vue2 Diagramming library which concentrate on flow layout field. (基于JavaScript/React/Vue2的流程图组件)
JavaScript
4,168
star
45

Tangram-Android

Tangram is a modular UI solution for building native page dynamically including Tangram for Android, Tangram for iOS and even backend CMS. This project provides the sdk on Android.
Java
4,107
star
46

coobjc

coobjc provides coroutine support for Objective-C and Swift. We added await method、generator and actor model like C#、Javascript and Kotlin. For convenience, we added coroutine categories for some Foundation and UIKit API in cokit framework like NSFileManager, JSON, NSData, UIImage etc. We also add tuple support in coobjc.
Objective-C
4,014
star
47

jstorm

Enterprise Stream Process Engine
Java
3,917
star
48

dragonwell8

Alibaba Dragonwell8 JDK
Java
3,826
star
49

LuaViewSDK

A cross-platform framework to build native, dynamic and swift user interface - 强大轻巧灵活的客户端动态化解决方案
Objective-C
3,707
star
50

f2etest

F2etest是一个面向前端、测试、产品等岗位的多浏览器兼容性测试整体解决方案。
JavaScript
3,562
star
51

Alink

Alink is the Machine Learning algorithm platform based on Flink, developed by the PAI team of Alibaba computing platform.
Java
3,479
star
52

GGEditor

A visual graph editor based on G6 and React
TypeScript
3,405
star
53

fastjson2

🚄 FASTJSON2 is a Java JSON library with excellent performance.
Java
3,353
star
54

cobar

a proxy for sharding databases and tables
Java
3,207
star
55

macaca

Automation solution for multi-platform. 多端自动化解决方案
3,159
star
56

designable

🧩 Make everything designable 🧩
TypeScript
3,120
star
57

GraphScope

🔨 🍇 💻 🚀 GraphScope: A One-Stop Large-Scale Graph Computing System from Alibaba | 一站式图计算系统
C++
3,103
star
58

lightproxy

💎 Cross platform Web debugging proxy
TypeScript
3,063
star
59

pont

🌉数据服务层解决方案
TypeScript
3,016
star
60

euler

A distributed graph deep learning framework.
C++
2,849
star
61

beidou

🌌 Isomorphic framework for server-rendered React apps
JavaScript
2,736
star
62

sentinel-golang

Sentinel Go enables reliability and resiliency for Go microservices
Go
2,684
star
63

pipcook

Machine learning platform for Web developers
TypeScript
2,497
star
64

kiwi

🐤 Kiwi-国际化翻译全流程解决方案
TypeScript
2,489
star
65

yugong

阿里巴巴去Oracle数据迁移同步工具(全量+增量,目标支持MySQL/DRDS)
Java
2,480
star
66

tsar

Taobao System Activity Reporter
C
2,446
star
67

jvm-sandbox-repeater

A Java server-side recording and playback solution based on JVM-Sandbox
Java
2,395
star
68

ChatUI

The UI design language and React library for Conversational UI
TypeScript
2,383
star
69

TProfiler

TProfiler是一个可以在生产环境长期使用的性能分析工具
Java
2,377
star
70

tidevice

tidevice can be used to communicate with iPhone device
Python
2,310
star
71

higress

Cloud Native API Gateway | 云原生API网关
Go
2,257
star
72

tair

A distributed key-value storage system developed by Alibaba Group
C++
2,128
star
73

dubbo-spring-boot-starter

Dubbo Spring Boot Starter
Java
2,099
star
74

RedisShake

redis-shake is a tool for synchronizing data between two redis databases. Redis-shake 是一个用于在两个 redis之 间同步数据的工具,满足用户非常灵活的同步、迁移需求。
Go
2,077
star
75

uirecorder

UI Recorder is a multi-platform UI test recorder.
JavaScript
2,052
star
76

LVS

A distribution of Linux Virtual Server with some advanced features. It introduces a new packet forwarding method - FULLNAT other than NAT/Tunneling/DirectRouting, and defense mechanism against synflooding attack - SYNPROXY.
C
1,947
star
77

EasyNLP

EasyNLP: A Comprehensive and Easy-to-use NLP Toolkit
Python
1,946
star
78

AliceMind

ALIbaba's Collection of Encoder-decoders from MinD (Machine IntelligeNce of Damo) Lab
Python
1,910
star
79

alpha

Alpha是一个基于PERT图构建的Android异步启动框架,它简单,高效,功能完善。 在应用启动的时候,我们通常会有很多工作需要做,为了提高启动速度,我们会尽可能让这些工作并发进行。但这些工作之间可能存在前后依赖的关系,所以我们又需要想办法保证他们执行顺序的正确性。Alpha就是为此而设计的,使用者只需定义好自己的task,并描述它依赖的task,将它添加到Project中。框架会自动并发有序地执行这些task,并将执行的结果抛出来。
HTML
1,873
star
80

GCanvas

A lightweight cross-platform graphics rendering engine. (超轻量的跨平台图形引擎) https://alibaba.github.io/GCanvas
C
1,857
star
81

Tangram-iOS

Tangram is a modular UI solution for building native page dynamically, including Tangram for Android, Tangram for iOS and even backend CMS. This project provides the sdk on iOS platform.
Objective-C
1,857
star
82

testable-mock

换种思路写Mock,让单元测试更简单
Java
1,800
star
83

LazyScrollView

An iOS ScrollView to resolve the problem of reusability in views.
Objective-C
1,775
star
84

compileflow

🎨 core business process engine of Alibaba Halo platform, best process engine for trade scenes. | 一个高性能流程编排引擎
Java
1,705
star
85

SREWorks

Cloud Native DataOps & AIOps Platform | 云原生数智运维平台
Java
1,696
star
86

EasyCV

An all-in-one toolkit for computer vision
Python
1,677
star
87

MongoShake

MongoShake is a universal data replication platform based on MongoDB's oplog. Redundant replication and active-active replication are two most important functions. 基于mongodb oplog的集群复制工具,可以满足迁移和同步的需求,进一步实现灾备和多活功能。
Go
1,648
star
88

xquic

XQUIC Library released by Alibaba is a cross-platform implementation of QUIC and HTTP/3 protocol.
C
1,604
star
89

mdrill

for千亿数据即席分析
Java
1,538
star
90

lowcode-demo

An enterprise-class low-code technology stack with scale-out design / 一套面向扩展设计的企业级低代码技术体系
TypeScript
1,536
star
91

ilogtail

Fast and Lightweight Observability Data Collector
C++
1,529
star
92

EasyRec

A framework for large scale recommendation algorithms.
Python
1,488
star
93

clusterdata

cluster data collected from production clusters in Alibaba for cluster management research
Jupyter Notebook
1,477
star
94

havenask

C++
1,463
star
95

async_simple

Simple, light-weight and easy-to-use asynchronous components
C++
1,455
star
96

kt-connect

A toolkit for Integrating with your kubernetes dev environment more efficiently
Go
1,454
star
97

Virtualview-Android

A light way to build UI in custom XML.
Java
1,454
star
98

tb_tddl

1,410
star
99

data-juicer

A one-stop data processing system to make data higher-quality, juicier, and more digestible for LLMs! 🍎 🍋 🌽 ➡️ ➡️🍸 🍹 🍷为大语言模型提供更高质量、更丰富、更易”消化“的数据!
Python
1,292
star
100

graph-learn

An Industrial Graph Neural Network Framework
C++
1,252
star