Googleのlibphonenumberの移植です。具体的には、Java実装を追跡しています。これはそのライブラリのリファレンス実装であり、C++やJavaScript版自体がそのポートです。このライブラリは世界中の数値解析や検証のために日常的に使われており、よく管理されています。

[!重要] このプロジェクトはlibphonenumberの厳密な移植です。そこに存在しない機能の機能リクエストはご遠慮ください。また、libphonenumberのメタデータも使用しているため、予期しない解析結果が発生した場合は、まずその問題がlibphonenumberに影響しているか確認し、そこで報告してください。オンラインデモを使って素早く解析結果を確認できます。

[!ヒント] 1.xから2.xへのアップグレードの詳細については、UPGRADING.mdを参照してください。

設置

使用法

更新中

メタデータ

buildmetadataコマンドは、上流リリースから埋め込まれたメタデータを再生成します。それは リリースをクローンし、パッケージ(コア)に埋め込まれたgzip化されたデータブロブを再構築します 地域メタデータ、短い番号、代替フォーマット、国コード→地域、キャリア、 ジオコーディングとタイムゾーンで、生成されたリリースを記録しています metadata/version.go。

☎️ phonenumbers

Go port of Google’s libphonenumber. Specifically it tracks the Java implementation — that library’s reference implementation, of which the C++ and JavaScript versions are themselves ports. This library is used daily in production for parsing and validation of numbers worldwide and is well maintained.

[!IMPORTANT] This project is a strict port of libphonenumber. Please do not submit feature requests for functionality that doesn’t exist there. It also uses the metadata from libphonenumber, so if you encounter unexpected parsing results, please first verify if the problem affects libphonenumber and report there if so. You can use the online demo to quickly check parsing results.

[!TIP] See UPGRADING.md for details on upgrading from 1.x to 2.x.

Installation

% go get github.com/nyaruka/phonenumbers/v2

Usage

import "github.com/nyaruka/phonenumbers/v2"

// parse our phone number
num, err := phonenumbers.Parse("8886418722", "US")

// check if it's a valid number for its region
valid := phonenumbers.IsValidNumber(num)

// format it using national format
formatted := phonenumbers.Format(num, phonenumbers.NATIONAL)

Updating

Metadata

The buildmetadata command regenerates the embedded metadata from an upstream release. It clones the release and rebuilds the gzipped data blobs embedded across the packages (core territory metadata, short numbers, alternate formats, country-code→region, carrier, geocoding, and timezone), recording the release it built from in the generated metadata/version.go.

# resolve and build from the latest upstream release
% go run ./cmd/buildmetadata

# or pin a specific release tag
% go run ./cmd/buildmetadata v9.0.31

This part is mechanical and fully automated.

Code

Regenerating the metadata is only half of a sync — the ported Go code also has to be reconciled against the new release’s Java logic changes, which is judgment work rather than a mechanical rebuild.

If you use Claude Code, the sync-upstream skill (.claude/skills/sync-upstream/SKILL.md) walks through the whole process — metadata regen plus the per-file code reconciliation. Invoke it with /sync-upstream or by asking it to sync with upstream. SYNC.md records the upstream version the port is synced against and the deliberate divergences from upstream.