From 37e5727179990acaf37c25e4111baf3773d74e6c Mon Sep 17 00:00:00 2001 From: zihluwang Date: Sat, 23 May 2026 09:26:06 +0800 Subject: [PATCH] docs: add regions4j documentation Add English and Chinese docs for regions4j, a Java library providing ISO 3166-1 regional metadata with Calendar Versioning. --- docs/en-gb/projects/regions4j/index.mdx | 98 +++++++++++++++++++++++ docs/zh-hans/projects/regions4j/index.mdx | 98 +++++++++++++++++++++++ 2 files changed, 196 insertions(+) create mode 100644 docs/en-gb/projects/regions4j/index.mdx create mode 100644 docs/zh-hans/projects/regions4j/index.mdx diff --git a/docs/en-gb/projects/regions4j/index.mdx b/docs/en-gb/projects/regions4j/index.mdx new file mode 100644 index 0000000..2f453c8 --- /dev/null +++ b/docs/en-gb/projects/regions4j/index.mdx @@ -0,0 +1,98 @@ +--- +title: regions4j +--- + +## Introduction + +**regions4j** is a lightweight, type-safe Java library that provides comprehensive metadata for world regions based on the ISO 3166-1 standard. It is designed to simplify internationalisation (i18n), telecommunication routing, and regional data management in Java-based enterprise applications. + +The library models every ISO 3166-1 country and territory as an enum constant, giving you compile-time safety and IDE autocompletion when referencing regions. With built-in O(1) lookups, zero external dependencies, and Java 8 compatibility, it is suitable for projects of any size — from microservices to monolithic enterprise systems. + +## Features + +- **ISO 3166-1 Compliant** — Full support for Alpha-2 (`abbreviation`) and Alpha-3 (`code`) formats across all assigned countries and territories. +- **Telecommunication Metadata** — Includes E.164 international dialling prefixes for every region. +- **Locality Support** — Default locale tags (`zh_HK`, `en_US`, `en_GB`, etc.) for each region to assist with i18n workflows. +- **High Performance** — Thread-safe, immutable internal hash maps provide constant-time lookups by abbreviation or code. +- **Zero Dependencies** — A pure Java library with no external overhead. +- **Calendar Versioning** — Versions follow a `YYYY.MM` scheme (e.g. `2025.12`) to transparently indicate the freshness of the underlying ISO data, rather than semantic versioning. + +## Core Schema + +Each region exposes four attributes: + +| Attribute | Type | Description | Example | +|----------------|--------|---------------------------------|------------------------------------| +| `abbreviation` | String | ISO 3166-1 alpha-2 abbreviation | `HK`, `US`, `GB`, `RU` | +| `code` | String | ISO 3166-1 alpha-3 code | `HKG`, `USA`, `GBR`, `RUS` | +| `callingCode` | String | E.164 international dialling prefix | `852`, `1`, `44`, `7` | +| `locale` | String | Default language and region tag | `zh_HK`, `en_US`, `en_GB`, `ru_RU` | + +## Installation + +**Maven:** + +```xml + + com.onixbyte + regions4j + 2025.12 + +``` + +**Gradle (Kotlin DSL):** + +```kotlin +implementation("com.onixbyte:regions4j:2025.12") +``` + +> **Versioning note:** This library uses Calendar Versioning (`YYYY.MM`) rather than Semantic Versioning. A version string like `2025.12` tells you immediately that the regional data reflects the ISO 3166-1 state as of December 2025. + +## Usage + +### Direct Access + +Reference any region directly via its enum constant: + +```java +Region uk = Region.UNITED_KINGDOM; + +uk.getAbbreviation(); // "GB" +uk.getCode(); // "GBR" +uk.getDialCode(); // "44" +uk.getLocale(); // "en_GB" +``` + +### Efficient Lookups + +Look up regions from string inputs — ideal for processing web requests, API payloads, or database records: + +```java +// By Alpha-2 abbreviation (case-sensitive) +Region region = Region.fromAbbreviation("HK"); + +// By Alpha-3 code (case-insensitive) +Region region = Region.fromCode("HKG"); +``` + +### Java Locale Integration + +Convert a region's locale string to a `java.util.Locale` for use with standard Java i18n APIs: + +```java +Region region = Region.CHINA; +Locale javaLocale = Locale.forLanguageTag(region.getLocale().replace("_", "-")); +javaLocale.getDisplayCountry(Locale.UK); // "China" +``` + +## Performance + +On first access, the library initialises all regions into immutable `HashMap` structures. Subsequent lookups via `fromAbbreviation()` and `fromCode()` are thread-safe and run in constant time — suitable for high-throughput request paths. + +## Requirements + +- Java 8 or later + +## License + +regions4j is open-source software released under the MIT License. diff --git a/docs/zh-hans/projects/regions4j/index.mdx b/docs/zh-hans/projects/regions4j/index.mdx new file mode 100644 index 0000000..df6a752 --- /dev/null +++ b/docs/zh-hans/projects/regions4j/index.mdx @@ -0,0 +1,98 @@ +--- +title: regions4j +--- + +## 介绍 + +**regions4j** 是一个轻量级、类型安全的 Java 库，基于 ISO 3166-1 标准提供全面的世界地区元数据。它旨在简化 Java 企业应用中的国际化（i18n）、电信路由和地区数据管理工作。 + +该库将每个 ISO 3166-1 国家和地区建模为枚举常量，使您在引用地区时获得编译期安全性和 IDE 自动补全支持。凭借内置的 O(1) 查找、零外部依赖和 Java 8 兼容性，它适用于任何规模的项目 — 从微服务到整体式企业系统。 + +## 特性 + +- **ISO 3166-1 合规** — 完整支持所有已分配国家和地区的 Alpha-2（`abbreviation`）和 Alpha-3（`code`）格式。 +- **电信元数据** — 包含每个地区的 E.164 国际拨号前缀。 +- **区域支持** — 每个地区提供默认的区域标签（如 `zh_HK`、`en_US`、`en_GB` 等），辅助 i18n 工作流。 +- **高性能** — 线程安全、不可变的内部哈希映射提供常量时间的缩写或代码查找。 +- **零依赖** — 纯 Java 库，无任何外部依赖。 +- **日历化版本管理** — 版本号采用 `YYYY.MM` 格式（如 `2025.12`），以透明地反映底层 ISO 数据的新鲜度，而非语义化版本号。 + +## 核心数据模型 + +每个地区暴露四个属性： + +| 属性 | 类型 | 描述 | 示例 | +|---|---|---|---| +| `abbreviation` | String | ISO 3166-1 alpha-2 缩写 | `HK`、`US`、`GB`、`RU` | +| `code` | String | ISO 3166-1 alpha-3 代码 | `HKG`、`USA`、`GBR`、`RUS` | +| `callingCode` | String | E.164 国际拨号前缀 | `852`、`1`、`44`、`7` | +| `locale` | String | 默认语言和地区标签 | `zh_HK`、`en_US`、`en_GB`、`ru_RU` | + +## 安装 + +**Maven:** + +```xml + + com.onixbyte + regions4j + 2025.12 + +``` + +**Gradle (Kotlin DSL):** + +```kotlin +implementation("com.onixbyte:regions4j:2025.12") +``` + +> **版本说明：** 该库使用日历化版本管理（`YYYY.MM`）而非语义化版本号。版本字符串如 `2025.12` 可以直观地告诉您地区数据反映的是 2025 年 12 月的 ISO 3166-1 状态。 + +## 使用 + +### 直接访问 + +通过枚举常量直接引用任何地区： + +```java +Region uk = Region.UNITED_KINGDOM; + +uk.getAbbreviation(); // "GB" +uk.getCode(); // "GBR" +uk.getDialCode(); // "44" +uk.getLocale(); // "en_GB" +``` + +### 高效查找 + +从字符串输入中查找地区 — 非常适合处理 Web 请求、API 负载或数据库记录： + +```java +// 按 Alpha-2 缩写查找（区分大小写） +Region region = Region.fromAbbreviation("HK"); + +// 按 Alpha-3 代码查找（不区分大小写） +Region region = Region.fromCode("HKG"); +``` + +### Java Locale 集成 + +将地区的 locale 字符串转换为 `java.util.Locale` 以配合标准 Java i18n API 使用： + +```java +Region region = Region.CHINA; +Locale javaLocale = Locale.forLanguageTag(region.getLocale().replace("_", "-")); +javaLocale.getDisplayCountry(Locale.UK); // "China" +``` + +## 性能 + +首次访问时，库会将所有地区初始化到不可变的 `HashMap` 结构中。后续通过 `fromAbbreviation()` 和 `fromCode()` 进行的查找均为线程安全且以常量时间运行 — 适用于高吞吐量的请求路径。 + +## 要求 + +- Java 8 或更高版本 + +## 许可证 + +regions4j 是采用 MIT 许可证发布的开源软件。