구글의 libphonenumber를 포팅한 것입니다. 구체적으로는 Java 구현체를 추적합니다 — 그 라이브러리의 참조 구현이며, C++와 JavaScript 버전 자체가 그 포팅입니다. 이 라이브러리는 전 세계적으로 숫자 해석과 검증을 위해 매일 운영 환경에서 사용되며 잘 관리되고 있습니다.

[! 중요] 이 프로젝트는 libphonenumber의 엄격한 이식입니다. libphonenumber에 없는 기능에 대한 기능 요청을 제출하지 마세요. 또한 libphonenumber의 메타데이터를 사용하므로, 예상치 못한 파싱 결과가 발생하면 먼저 libphonenumber에 문제가 적용되는지 확인하고 그곳에 보고해 주세요. 온라인 데모를 통해 빠르게 파싱 결과를 확인할 수 있습니다.

[! 팁] 1.x에서 2.x로의 업그레이드에 대한 자세한 내용은 UPGRADING.md를 참조하세요.

설치

사용

업데이트 중

메타데이터

buildmetadata 명령어는 업스트림 릴리스에서 내장된 메타데이터를 재생성합니다. 릴리스를 복제하고 패키지(코어) 내에 내장된 gzipped 데이터 블롭을 재구성합니다 지역 메타데이터, 짧은 번호, 대체 형식, 국가 코드→지역, 통신사, 지오코딩과 시간대), 생성된 릴리스를 기록하는 데 사용되었습니다 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.