Unicode Emoji Annotations
Unicode standard compliant emoji annotations (internationalized text-to-speech descriptions and keywords) with extensions provided by the community
- lightweight, precompiled, easy to use JSON data with a minimalistic API
- straight from the source, compiled directly from unicode repository data files
- up-to-date, supporting the latest stable unicode CLDR version 30
- best used in combination with the unicode-emoji-data module
This project aims to preserve CLDR emoji annotation data with respect to the original source as closely as possible while offering supplemental community authored annotation data.
Warning: ~1MB file ahead! Have a look at this table to see an example of what data this library provides. Especially row #1152 is interesting as it shows a CLDR annotation being combined with multiple supplemental community annotations.
Check out emoji-finder to see an example of how this module can be utilized in a real application.
Supplemental annotation data is being authored by a community that will hopefully build around this project in the future. An initial set of community annotations created by the original project maintainer serves as a baseline for further discussions and development.
The need for community authored annotations arises from the fact that the CLDR annotation data provided by unicode is incomplete. Not every emoji is being covered and incompleteness varies across supported languages. Furthermore, some annotations might need to be extended or overridden in order to semantically improve the description of their respective emoji.
Great care is taken so that community authored text-to-speech descriptions and keywords always ever describe solely the semantics of the emoji based on the official unicode emoji names. The annotations must never be based on the actual appearance of emoji, as the official unicode name often leaves room for interpretation and vendors use this to implement the appearance very differently from one another.
Supported Languages
This table shows languages for which CLDR annotations are included in this library and the respective percentaged coverage of missing CLDR data by community provided supplemental annotations. Feel free to create an issue if you like an additional language to be added.
Language | CLDR | Community Coverage |
---|
de | ✓ | 100% |
en | ✓ | 100% |
API
Requiring/importing unicode-emoji-annotations
gives you the following API to work with:
cldrAnnotations
communityAnnotations
combinedAnnotationsForLanguage
cldrAnnotations
{
...
de: [..., { }, ...],
en: [..., { }, ...],
...
}
Arrays of emoji annotations grouped by language (two-letter code), compiled from unicode CLDR data files.
A typical (english) CLDR annotation looks like this:
{
sequence: '1F61C',
tts: 'face with stuck-out tongue & winking eye',
keywords: [
'eye',
'face',
'joke',
'tongue',
'wink'
]
}
Properties of an emoji annotation explained:
-
sequence
normalized code point sequence (sequence without any variation selector or modifier applied) e.g. 1F61C
; use it for mapping the annotation to a specific (emoji) unicode character or connecting to further meta data (e.g. unicode-emoji-data or emoji-datasource)
-
tts
text-to-speech description e.g. 'face with stuck-out tongue & winking eye'
(en
) or 'Zwinkernder Smiley mit herausgestreckter Zunge'
(de
)
-
keywords
array of keywords e.g. ['eye', 'face', 'joke', 'tongue', 'wink']
(en
) or ['herausgestreckte Zunge', 'Zwinkern', 'Gesicht']
(de
)
{
global: [..., { }, ...],
...
de: [..., { }, ...],
en: [..., { }, ...],
...
}
Arrays of supplemental emoji annotations grouped by language (two-letter code), authored and maintained by the community.
Community annotations might include entirely new entries for supporting emoji that are not currently covered by CLDR, but also additions to keywords
of existing CLDR annotations. In some rare cases we might even decide to override the tts
description of existing CLDR annotations where necessary in order to improve semantics.
global
contains language independent additions to keywords
, e.g. text emoticons ;-)
(tts
overrides would make no sense here).
Example of a global supplemental community annotation:
{
sequence: '1F61C',
keywords: [
';-P',
';P',
';-b',
';b'
]
}
Example of an english supplemental community annotation:
{
sequence: '1F61C',
keywords: [
'cheeky'
]
}
Example of a german supplemental community annotation:
{
sequence: '1F61C',
keywords: [
'frech'
]
}
combinedAnnotationsForLanguage
function (language) {}
Selectively extends/overrides CLDR annotations with community authored content for the specified language
(e.g. 'de'
, 'en'
), combining:
language
specific CLDR annotations (if available)language
specific community annotations (if available)- global community annotations (if available)
Overrides tts
, concatenates keywords
.
returns an array of combined emoji annotations:
[..., { }, ...]
Usage
CommonJS
const unicodeEmojiAnnotations = require('unicode-emoji-annotations');
const englishCldrAnnotations = unicodeEmojiAnnotations.cldrAnnotations.en;
const englishCommunityAnnotations = unicodeEmojiAnnotations.communityAnnotations.en;
const globalCommunityAnnotations = unicodeEmojiAnnotations.communityAnnotations.global;
const englishAnnotations = unicodeEmojiAnnotations.combinedAnnotationsForLanguage('en');
ES6/babel
import { cldrAnnotations, communityAnnotations, combinedAnnotationsForLanguage } from 'unicode-emoji-annotations';
const englishCldrAnnotations = cldrAnnotations.en;
const englishCommunityAnnotations = communityAnnotations.en;
const globalCommunityAnnotations = communityAnnotations.global;
const englishAnnotations = combinedAnnotationsForLanguage('en');
Install
Stable unicode 9 cldr 30 data for emoji 4:
npm install unicode-emoji-annotations
Beta unicode 10 cldr 31 data for emoji 5:
npm install unicode-emoji-annotations@next
License
MIT
Development
Status
![Codecov](https://img.shields.io/codecov/c/github/dematerializer/unicode-emoji-annotations.svg?style=flat-square)