weather-i18n

A lightweight, fully typed TypeScript library for internationalizing, validating, and mapping weather condition codes (WMO 4677) with multilingual descriptions and popular icon sets.

Features

• 🌐 Internationalization (i18n): Translate WMO 4677 weather codes into multiple languages (en, es) with day/night phase support (day / night) and fallback language support.
• 📐 Complete Specification: Comprehensive definitions, human-readable keys (key), and reverse mappings for WMO 4677 weather codes.
• 🛡️ Zod Validation: Flexible schema to validate and transform numeric inputs (95), string values ("95"), or human-readable keys ("thunderstorm_slight_moderate_no_hail").
• 🎨 Icon Mapping: Automatically map weather codes to popular icon packs such as Meteocons, Material Weather Icons and Pixelarticons, with both day and night variants.
• 📦 Tree-Shaking & Subpath Imports: Import only what you need or access the raw JSON data directly.

Installation

# Using pnpm
pnpm add weather-i18n

# Using npm
npm install weather-i18n

# Using yarn
yarn add weather-i18n

Import Options

Once the package is installed, you can import it in different ways depending on your bundling strategy and project architecture.

1. Main Import (Full Bundle)

import { WMO4677 } from "weather-i18n";

// Unified access to spec, i18n, validator, and icons
const desc = WMO4677.i18n("es")(95, "day");
const parsed = WMO4677.validator.parse("95");

2. WMO 4677 Module

import WMO4677 from "weather-i18n/wmo_4677";

const desc = WMO4677.i18n("en")(3, "night");

3. Subpath Imports

To optimize your bundle size or use specific features independently:

// Internationalization
import WMO4677I18n from "weather-i18n/wmo_4677/i18n";
const getDesc = WMO4677I18n("es", "en");
console.log(getDesc(95, "day")); // "Thunderstorm"

// Complete specification
import WMO4677Spec from "weather-i18n/wmo_4677/spec";
console.log(WMO4677Spec[95].key); // "thunderstorm_slight_moderate_no_hail"

// Zod validator
import WMO4677Validator from "weather-i18n/wmo_4677/validator";
const result = WMO4677Validator.parse("05");

// Icons (All)
import WMO4677Icons from "weather-i18n/wmo_4677/icons";
console.log(WMO4677Icons.meteocons(95, "day"));

// Individual icon helpers
import WMO4677Meteocons from "weather-i18n/wmo_4677/icons/meteocons";
import WMO4677MaterialWeatherIcons from "weather-i18n/wmo_4677/icons/material-weather-icons";

console.log(WMO4677Meteocons(95, "night", {
  withUrlTemplate: true,
  variant: "flat",
  format: "svg-static"
}));
console.log(WMO4677MaterialWeatherIcons(95, "day"));

4. Direct JSON Imports

You can import the original JSON data files using Import Attributes (or assertions, depending on your environment):

import WMO4677I18nEN from "weather-i18n/wmo_4677/data/i18n/en.json" with { format: "json" };
import WMO4677I18nES from "weather-i18n/wmo_4677/data/i18n/es.json" with { format: "json" };
import WMO4677Meteocons from "weather-i18n/wmo_4677/data/icons/meteocons.json" with { format: "json" };
import WMO4677MaterialWeatherIcons from "weather-i18n/wmo_4677/data/icons/material-weather-icons.json" with { format: "json" };

(Note: In Node.js v20+/v22+ and modern bundlers, with { type: "json" } is also supported.)

API Overview

Internationalization (i18n)

Create a formatter by specifying the desired language and, optionally, a fallback language:

import WMO4677I18n from "weather-i18n/wmo_4677/i18n";

const getDesc = WMO4677I18n("es", "en");

// Get the daytime description for code 95
const daytimeText = getDesc(95, "day"); // "Tormenta"

// Get the nighttime description
const nighttimeText = getDesc(95, "night");

Zod Validator (validator)

Parses input values as integers (0-99), strings ("05"), or human-readable keys ("haze"), returning a structured object:

import WMO4677Validator from "weather-i18n/wmo_4677/validator";

const data = WMO4677Validator.parse("5");
// Result:
// {
//   code: 5,
//   key: "haze",
//   description: "Haze"
// }

Development & Scripts

If you'd like to contribute or run the local build and validation scripts:

# Install dependencies
pnpm install

# Compile TypeScript into /dist
pnpm build

# Run tests and validation
pnpm test

License

ISC