internationalized-color

Internationalized Color

A locale-aware color naming library that maps any color to its closest name in 74 languages. Built on culori for color math, it uses k-d trees in OkLab perceptual color space for fast, accurate nearest-neighbor lookup — so the names you get match what humans actually see.

Features

• 74 languages — Arabic, Japanese, Hindi, French, Chinese, and 69 more, each with survey-derived color names
• 3 naming tiers — basic (Berlin-Kay ~11 terms), extended (common names), and traditional (cultural: Japanese wa-iro, Chinese traditional, Korean obangsaek)
• Cross-language translation — translate color names between any two supported languages
• Perceptually accurate — nearest-neighbor search in OkLab space correlates with human color perception
• O(log n) lookup — k-d tree indexing, lazily built and cached per locale
• Immutable Color class — parse, convert, mix, lighten/darken across any CSS Color Level 4 space
• Tree-shakeable — import only the locales and color spaces you need
• Zero config — works with any CSS color string out of the box

Install

npm install internationalized-color

pnpm add internationalized-color

yarn add internationalized-color

bun add internationalized-color

Usage

Register color spaces and locales, then use the standalone functions:

import 'internationalized-color/css'; // registers all CSS Color Level 4 spaces
import { useLocale, nameColor, nearestColors, lookupColor, translateColor } from 'internationalized-color';
import { en } from 'internationalized-color/locales/en';
import { ar } from 'internationalized-color/locales/ar';
import { ja } from 'internationalized-color/locales/ja';

// Register locales (like culori's useMode)
useLocale(en);
useLocale(ar);
useLocale(ja);

// Name a color in English
nameColor('#ff6347', 'en'); // → "tomato"

// Name the same color in Japanese
nameColor('#ff6347', 'ja'); // → "朱色"

// Name at the basic (Berlin-Kay 11) tier only
nameColor('#ff6347', 'en', { level: 'basic' }); // → "red"

// Translate a color name across languages
translateColor('red', 'en', 'ar'); // → "أحمر"
translateColor('red', 'en', 'ja'); // → "赤"

// Find the N closest named colors
nearestColors('#ff6347', 'en', 3); // → ["tomato", "orangered", "coral"]

// Reverse lookup: name → Color
lookupColor('tomato', 'en'); // → Color (oklab)

You can also pass a ColorDictionary directly instead of a locale string, bypassing the registry:

import { en } from 'internationalized-color/locales/en';
import { nameColor } from 'internationalized-color';

nameColor('#ff6347', en); // works without useLocale()

Color formats

Powered by culori, any CSS Color Level 4 format is supported:

import 'internationalized-color/css';
import { Color } from 'internationalized-color';

// Hex
Color.parse('#ff6347');

// CSS named colors
Color.parse('tomato');

// RGB
Color.parse('rgb(255, 99, 71)');

// HSL
Color.parse('hsl(9, 100%, 64%)');

// HWB
Color.parse('hwb(9 28% 0%)');

// OkLab
Color.parse('oklab(0.7 0.1 0.1)');

// OkLCH
Color.parse('oklch(0.7 0.15 50)');

// Lab
Color.parse('lab(62 45 47)');

// LCH
Color.parse('lch(62 65 46)');

// Display P3
Color.parse('color(display-p3 1 0.39 0.28)');

Tree-shakeable setup

If you don't need all CSS color spaces, register only what you use via culori's useMode:

import { useMode, modeRgb, modeOklab, modeOklch } from 'culori/fn';
import { Color } from 'internationalized-color';

useMode(modeRgb);
useMode(modeOklab);
useMode(modeOklch);

Color manipulation

The Color class is an immutable value object — every method returns a new instance.

import 'internationalized-color/css';
import { Color } from 'internationalized-color';

// Create colors
const tomato = Color.parse('#ff6347');
const sky = Color.from('oklch(0.75 0.15 230)');  // accepts string, Color, or culori object
const custom = Color.create('rgb', { r: 0.5, g: 0.2, b: 0.8 });

// Convert between color spaces
const lab = tomato.toOklab();
const lch = tomato.toOklch();
const hsl = tomato.toHsl();
const p3 = tomato.toP3();
const generic = tomato.to('rec2020');  // any registered mode

// Read channels
tomato.mode;                   // → "rgb"
tomato.get('r');               // → 1
tomato.getRed();               // → 1
tomato.channels;               // → ["r", "g", "b"]
tomato.entries();              // → [["r", 1], ["g", 0.388...], ["b", 0.278...]]
tomato.has('r');               // → true

// Modify channels (returns new Color)
tomato.set({ r: 0.5 });
tomato.setAlpha(0.8);

// Mix colors (defaults to 50% blend in OkLab)
tomato.mix(sky);               // perceptually uniform blend
tomato.mix(sky, 0.25);         // 25% toward sky
tomato.mix('#0000ff', 0.5, 'oklch');  // mix in OkLCH space

// Lighten / darken (adjusts OkLab lightness)
tomato.lighten(0.1);
tomato.darken(0.2);

// Perceptual distance & equality
tomato.deltaE(sky);            // Euclidean distance in OkLab
tomato.equals(sky);            // exact match
tomato.equals(sky, 0.05);     // within perceptual tolerance

// Serialize
tomato.toString();             // → "color(srgb 1 0.38824 0.27843)"
tomato.toHex();                // → "#ff6347"
tomato.toJSON();               // → { mode: "rgb", channels: { r: 1, g: 0.388..., b: 0.278... } }
tomato.toObject();             // raw culori color object

Supported Languages

74 languages with ISO 639-1 codes, plus 3 traditional/cultural color sets (Japanese wa-iro, Chinese traditional, Korean obangsaek).

Full language list

Code	Language	Code	Language
aa	🇩🇯 Afar	na	🇳🇷 Nauru
ab	🇬🇪 Abkhazian	nb	🇳🇴 Norwegian Bokmål
af	🇿🇦 Afrikaans	ne	🇳🇵 Nepali
ak	🇬🇭 Akan	nl	🇳🇱 Dutch
am	🇪🇹 Amharic	nn	🇳🇴 Norwegian Nynorsk
ar	🇸🇦 Arabic	no	🇳🇴 Norwegian
az	🇦🇿 Azerbaijani	ny	🇲🇼 Chichewa
bg	🇧🇬 Bulgarian	oc	🇫🇷 Occitan
bn	🇧🇩 Bengali	pa	🇮🇳 Punjabi
ca	🇪🇸 Catalan	pl	🇵🇱 Polish
cr	🇨🇦 Cree	ps	🇦🇫 Pashto
cs	🇨🇿 Czech	pt	🇵🇹 Portuguese
cy	🏴󠁧󠁢󠁷󠁬󠁳󠁿 Welsh	ro	🇷🇴 Romanian
da	🇩🇰 Danish	ru	🇷🇺 Russian
de	🇩🇪 German	si	🇱🇰 Sinhala
el	🇬🇷 Greek	sk	🇸🇰 Slovak
en	🇬🇧 English	sl	🇸🇮 Slovenian
es	🇪🇸 Spanish	sm	🇼🇸 Samoan
et	🇪🇪 Estonian	so	🇸🇴 Somali
fa	🇮🇷 Persian	sq	🇦🇱 Albanian
fi	🇫🇮 Finnish	sr	🇷🇸 Serbian
fr	🇫🇷 French	su	🇮🇩 Sundanese
ga	🇮🇪 Irish	sv	🇸🇪 Swedish
gu	🇮🇳 Gujarati	ta	🇮🇳 Tamil
he	🇮🇱 Hebrew	te	🇮🇳 Telugu
hi	🇮🇳 Hindi	th	🇹🇭 Thai
hr	🇭🇷 Croatian	tl	🇵🇭 Tagalog
hu	🇭🇺 Hungarian	tr	🇹🇷 Turkish
id	🇮🇩 Indonesian	uk	🇺🇦 Ukrainian
is	🇮🇸 Icelandic	ur	🇵🇰 Urdu
it	🇮🇹 Italian	vi	🇻🇳 Vietnamese
ja	🇯🇵 Japanese	zh	🇨🇳 Chinese
ka	🇬🇪 Georgian	ja-traditional	🇯🇵 Japanese wa-iro
kn	🇮🇳 Kannada	zh-traditional	🇨🇳 Chinese traditional
ko	🇰🇷 Korean	ko-traditional	🇰🇷 Korean obangsaek
lb	🇱🇺 Luxembourgish
lt	🇱🇹 Lithuanian
lv	🇱🇻 Latvian
mk	🇲🇰 Macedonian
ml	🇮🇳 Malayalam
ms	🇲🇾 Malay
my	🇲🇲 Burmese

Data Source

Color naming data is derived from the Many Languages, Many Colors Dataset:

Younghoon Kim, Kyle Thayer, Gabriella Silva Gorsky, and Jeffrey Heer. "Color Names Across Languages: Salient Colors and Term Translation in Multilingual Color Naming Models." EuroVis, 2019.

Survey data from github.com/uwdata/color-naming-in-different-languages.

Help Improve the Data

The color naming models behind this library are only as good as the survey data they're built on. More responses — especially for underrepresented languages — lead to better color names and more accurate translations. You can contribute by taking the 15-minute color perception survey from the Many Languages, Many Colors project. Every response helps refine the models that power this library.

Regenerating Locale Data

To regenerate locale files from the dataset:

git clone https://github.com/uwdata/color-naming-in-different-languages
bun scripts/generate-locales.ts ./color-naming-in-different-languages/model/cleaned_color_data_by_lang

License

MIT