docs(readme): README를 한국어로 정리한다

2026-05-29 05:41:30 +09:00 · 2026-05-29 05:41:30 +09:00 · 511d5a4dca
commit 511d5a4dca
parent 33c85f8faa
1 changed files with 81 additions and 81 deletions
--- a/README.md
+++ b/README.md
@ -1,116 +1,116 @@
 # Proto Socket

-Binary socket protocol library for bidirectional, heterogeneous communication across languages and platforms.
+Proto Socket은 여러 언어와 플랫폼 사이에서 양방향 통신을 하기 위한 바이너리 소켓 프로토콜 라이브러리다.

-Built on Protocol Buffers with TCP length-prefixed framing, WebSocket binary frames, type-based message routing, request-response correlation, and built-in heartbeat.
+Protocol Buffers 직렬화, TCP 4바이트 빅엔디안 길이 프리픽스 프레이밍, WebSocket 바이너리 프레임, 타입 기반 메시지 라우팅, 요청-응답 상관관계, 내장 하트비트를 제공한다.

 ---

-## Current Status
+## 현재 상태

-Proto Socket currently treats the Dart, Go, Kotlin, Python, and TypeScript implementations as the available compatibility set for protocol `0.1`.
+현재 프로토콜 `0.1`의 사용 가능 호환 구현은 Dart, Go, Kotlin, Python, TypeScript다.

-The project is in a stabilization and maintenance pass before adding more language targets or publishing package registry releases. Git-based consumption from this repository is the primary supported workflow for now. C# and Swift remain planned targets, but implementation work is deferred until there is concrete demand.
+이 프로젝트는 새 언어 대상을 늘리거나 패키지 registry에 배포하기 전 안정화와 유지보수 단계에 있다. 지금은 이 저장소를 Git 기반으로 소비하는 흐름을 기본 지원 방식으로 둔다. C#과 Swift는 계획된 대상이지만, 실제 수요가 생기기 전까지 구현을 미룬다.

-Use the local validation matrix as the stability gate for protocol or implementation changes:
+프로토콜이나 구현을 바꿀 때는 아래 로컬 검증 매트릭스를 안정성 gate로 사용한다.

 ```bash
 bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
 ```

-Protocol or public API changes should be treated as compatibility work: update the relevant docs, regenerate protobuf bindings when needed, and keep the full validation matrix passing.
+프로토콜 또는 공개 API 변경은 호환성 작업으로 다룬다. 관련 문서를 갱신하고, 필요한 경우 protobuf binding을 재생성하며, 전체 검증 매트릭스가 통과해야 한다.

 ---

-## Design Principles
+## 설계 원칙

- Keep the core transport layer thin and stable
- Provide only the minimum common foundation for cross-language communication
- Standardize framing, serialization, routing, request-response correlation, and heartbeat
- Treat Protocol Buffers as the core protocol dependency. Other runtime dependencies should be native-first, narrowly scoped, and proportional to the feature they implement
- Do not embed application semantics into the protocol core
- Domain-specific concerns such as auth, session, agent workflow, chat features, and game logic belong in upper-layer implementations
+- core transport layer는 얇고 안정적으로 유지한다.
+- 언어 간 통신에 필요한 최소 공통 기반만 제공한다.
+- framing, serialization, routing, request-response correlation, heartbeat를 표준화한다.
+- Protocol Buffers를 핵심 프로토콜 의존성으로 둔다. 다른 런타임 의존성은 native-first, 좁은 범위, 기능에 비례한 수준으로 유지한다.
+- 애플리케이션 의미를 프로토콜 core에 넣지 않는다.
+- auth, session, agent workflow, chat, game logic 같은 도메인 관심사는 상위 레이어 구현의 책임이다.

 ---

-## Protocol
+## 프로토콜

-See [PROTOCOL.md](PROTOCOL.md) for the full wire format specification.
+전체 wire format 명세는 [PROTOCOL.md](PROTOCOL.md)를 본다.

-```
+```text
 [4-byte big-endian length] [PacketBase protobuf bytes]
 ```

-For WebSocket/WSS transports, each binary frame contains one `PacketBase` protobuf payload without the TCP length header.
+WebSocket/WSS transport에서는 각 binary frame이 TCP length header 없이 `PacketBase` protobuf payload 하나를 담는다.

-Protocol compatibility is tracked separately from language package versions. See [VERSIONING.md](VERSIONING.md). Even while packages are not published, the checked-in implementations must preserve the documented protocol contract.
+프로토콜 호환성은 언어별 package version과 분리해서 추적한다. 자세한 정책은 [VERSIONING.md](VERSIONING.md)를 본다. 패키지를 아직 registry에 배포하지 않더라도, 저장소에 포함된 구현은 문서화된 프로토콜 계약을 지켜야 한다.

 ---

-## Implementations
+## 구현체

-| Language | Status | Path | Use case |
-|----------|--------|------|----------|
-| Dart | Available | [dart/](dart/) | Flutter, Dart server |
-| Kotlin | Available | [kotlin/](kotlin/) | Android, JVM |
-| Go | Available | [go/](go/) | Server, tooling, scripting |
-| TypeScript | Available | [typescript/](typescript/) | Browser, Node.js |
-| Python | Available | [python/](python/) | Server, tooling, scripting |
-| C# | Planned / deferred | `csharp/` | Unity, .NET |
-| Swift | Planned / deferred | `swift/` | iOS, macOS |
+| 언어 | 상태 | 경로 | 사용처 |
+|------|------|------|--------|
+| Dart | 사용 가능 | [dart/](dart/) | Flutter, Dart server |
+| Kotlin | 사용 가능 | [kotlin/](kotlin/) | Android, JVM |
+| Go | 사용 가능 | [go/](go/) | Server, tooling, scripting |
+| TypeScript | 사용 가능 | [typescript/](typescript/) | Browser, Node.js |
+| Python | 사용 가능 | [python/](python/) | Server, tooling, scripting |
+| C# | 계획 / 보류 | `csharp/` | Unity, .NET |
+| Swift | 계획 / 보류 | `swift/` | iOS, macOS |

-New language implementations should start from [PORTING_GUIDE.md](PORTING_GUIDE.md) and the templates in [agent-ops/skills/project/add-proto-socket-crosstest-language/templates/](agent-ops/skills/project/add-proto-socket-crosstest-language/templates/). Mark an implementation available only after its same-language tests and cross-language tests pass.
+새 언어 구현은 [PORTING_GUIDE.md](PORTING_GUIDE.md)와 [agent-ops/skills/project/add-proto-socket-crosstest-language/templates/](agent-ops/skills/project/add-proto-socket-crosstest-language/templates/)의 템플릿에서 시작한다. 동일 언어 테스트와 크로스 언어 테스트가 통과한 뒤에만 구현 상태를 사용 가능으로 표시한다.

-Keep implementation status here as the public snapshot. Current work context is selected through [agent-roadmap/current.md](agent-roadmap/current.md), and broader roadmap direction lives in [agent-roadmap/ROADMAP.md](agent-roadmap/ROADMAP.md).
+현재 구현 상태는 이 README를 공개 snapshot으로 본다. 현재 작업 맥락은 [agent-roadmap/current.md](agent-roadmap/current.md)에서 선택하고, 큰 로드맵 방향은 [agent-roadmap/ROADMAP.md](agent-roadmap/ROADMAP.md)에 둔다.

 ---

-## Common Commands
+## 주요 명령

-| Purpose | Command | Notes |
-|---------|---------|-------|
-| Full local validation | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` | Proto sync, same-language tests, and all available cross-language checks |
-| Proto schema sync check | `tools/check_proto_sync.sh` | Verifies language proto copies match `proto/message_common.proto` except allowed language options |
-| Regenerate protobuf bindings | `tools/generate_proto.sh` | Run after changing the canonical proto schema |
-| Dart tests | `cd dart && dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js` | Dart VM/IO tests and web import compile check |
-| Go tests | `cd go && go test ./...` | Go same-language checks |
-| Kotlin tests | `cd kotlin && ./gradlew test` | Kotlin same-language checks |
-| Python tests | `cd python && python3 -m pytest -q` | Python same-language checks |
-| TypeScript checks | `cd typescript && npm run check && npm test` | TypeScript type check and tests |
+| 목적 | 명령 | 비고 |
+|------|------|------|
+| 전체 로컬 검증 | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` | proto sync, 동일 언어 테스트, 사용 가능 구현의 크로스 언어 검증을 실행한다. |
+| Proto schema sync 확인 | `tools/check_proto_sync.sh` | 언어별 proto copy가 허용된 언어 옵션을 제외하고 `proto/message_common.proto`와 일치하는지 확인한다. |
+| Protobuf binding 재생성 | `tools/generate_proto.sh` | canonical proto schema를 바꾼 뒤 실행한다. |
+| Dart 테스트 | `cd dart && dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js` | Dart VM/IO 테스트와 web import compile 확인 |
+| Go 테스트 | `cd go && go test ./...` | Go 동일 언어 검증 |
+| Kotlin 테스트 | `cd kotlin && ./gradlew test` | Kotlin 동일 언어 검증 |
+| Python 테스트 | `cd python && python3 -m pytest -q` | Python 동일 언어 검증 |
+| TypeScript 확인 | `cd typescript && npm run check && npm test` | TypeScript type check와 테스트 |

 ---

-## Repository Structure
+## 저장소 구조

-| Path | Role |
+| 경로 | 역할 |
 |------|------|
-| [proto/](proto/) | Canonical protobuf schema source |
-| [dart/](dart/) | Dart / Flutter implementation and tests |
-| [go/](go/) | Go implementation, tests, and Go-led crosstests |
-| [kotlin/](kotlin/) | Kotlin / JVM implementation and crosstests |
-| [python/](python/) | Python implementation and crosstests |
-| [typescript/](typescript/) | TypeScript implementation and crosstests |
-| [tools/](tools/) | Proto generation and sync helpers |
-| [examples/](examples/) | Consumer-oriented examples |
-| [agent-ops/](agent-ops/) | Project rules, roadmap, and repeatable agent workflows |
+| [proto/](proto/) | canonical protobuf schema 원본 |
+| [dart/](dart/) | Dart / Flutter 구현체와 테스트 |
+| [go/](go/) | Go 구현체, 테스트, Go 주도 crosstest |
+| [kotlin/](kotlin/) | Kotlin / JVM 구현체와 crosstest |
+| [python/](python/) | Python 구현체와 crosstest |
+| [typescript/](typescript/) | TypeScript 구현체와 crosstest |
+| [tools/](tools/) | proto 생성과 sync helper |
+| [examples/](examples/) | 소비자 지향 예제 |
+| [agent-ops/](agent-ops/) | 프로젝트 규칙, 로드맵, 반복 agent workflow |

 ---

-## Quick Start (Dart)
+## 빠른 시작: Dart

 ```dart
 import 'package:proto_socket/proto_socket.dart';

-// 1. Define your message in message_common.proto, generate with protoc
+// 1. message_common.proto에 메시지를 정의하고 protoc로 생성한다.

-// 2. Implement a client
+// 2. client를 구현한다.
 class MyClient extends ProtobufClient {
  MyClient(Socket socket) : super(socket, 30, 10, {
    MyMessage.getDefault().info_.qualifiedMessageName: MyMessage.fromBuffer,
  });
 }

-// 3. Implement a server
+// 3. server를 구현한다.
 class MyServer extends ProtobufServer {
  MyServer() : super('0.0.0.0', 9090, (socket) => MyClient(socket));

@ -120,11 +120,11 @@ class MyServer extends ProtobufServer {
  }
 }

-// 4. Start
+// 4. server를 시작한다.
 final server = MyServer();
 await server.start();

-// 5. Connect and send
+// 5. 연결하고 메시지를 보낸다.
 final socket = await Socket.connect('localhost', 9090);
 final client = MyClient(socket);
 await client.send(MyMessage()..text = 'hello');
@ -132,20 +132,20 @@ await client.send(MyMessage()..text = 'hello');

 ---

-## Adding Message Types
+## 메시지 타입 추가

-Edit the canonical proto at `proto/message_common.proto`, then regenerate all checked-in bindings:
+canonical proto인 `proto/message_common.proto`를 수정한 뒤, 저장소에 포함된 모든 binding을 재생성한다.

 ```bash
 tools/generate_proto.sh
 tools/check_proto_sync.sh
 ```

-The Go and Kotlin proto copies are allowed to keep only language-specific options such as `option go_package` or Java package/class options. `tools/check_proto_sync.sh` fails with a diff when their message schema drifts from `proto/message_common.proto`.
+Go와 Kotlin proto copy에는 `option go_package`, Java package/class option 같은 언어별 옵션만 추가로 허용한다. 메시지 schema가 `proto/message_common.proto`와 달라지면 `tools/check_proto_sync.sh`가 diff와 함께 실패한다.

 ---

-## Quick Start (Go)
+## 빠른 시작: Go

 ```go
 package main
@ -207,27 +207,27 @@ func main() {
 }
 ```

-Go also provides:
+Go 구현체는 다음 표면도 제공한다.

 - TCP: `NewTcpServer`, `DialTcp`, `NewTcpServerTLS`, `DialTcpTLS`
 - WebSocket: `NewWsServer`, `DialWs`, `NewWsServerTLS`, `DialWss`
 - Shared helpers: `Send`, `SendRequest`, `AddListenerTyped`, `AddRequestListenerTyped`, `Broadcast`

-If you want a copyable scaffold for using this module from another repository, see [examples/go-module-consumer/](examples/go-module-consumer/).
+다른 저장소에서 이 모듈을 사용하는 복사 가능한 scaffold가 필요하면 [examples/go-module-consumer/](examples/go-module-consumer/)를 본다.

 ---

-## Running Tests
+## 테스트 실행

-Local commands are documented here for development and troubleshooting. The repeatable repository-local validation entry point is:
+개발과 문제 재현을 위한 로컬 명령은 이 문서에 정리한다. 반복 가능한 저장소 로컬 검증 진입점은 다음 명령이다.

 ```bash
 bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
 ```

-It runs proto schema sync, same-language tests, and cross-language checks, then prints PASS/FAIL tables with reproduction commands for failures. Use `--proto`, `--unit`, or `--cross` to run a smaller slice.
+이 명령은 proto schema sync, 동일 언어 테스트, 크로스 언어 검증을 실행하고, 실패가 있으면 재현 명령과 함께 PASS/FAIL 표를 출력한다. 더 작은 범위만 확인하려면 `--proto`, `--unit`, `--cross`를 사용한다.

-External CI runner integration is deferred until the parent `../oto` project standardizes its execution path. Until then, the local matrix above is the project stability gate.
+외부 CI runner 연동은 상위 `../oto` 프로젝트가 실행 경로를 표준화할 때까지 보류한다. 그 전까지는 위 로컬 매트릭스를 프로젝트 안정성 gate로 본다.

 Proto schema sync:

@ -235,7 +235,7 @@ Proto schema sync:
 tools/check_proto_sync.sh
 ```

-Same-language checks:
+동일 언어 검증:

 ```bash
 cd dart
@ -265,7 +265,7 @@ npm run check
 npm test
 ```

-Cross-language checks:
+크로스 언어 검증:

 ```bash
 cd go
@ -307,9 +307,9 @@ cd typescript
 ./node_modules/.bin/tsx crosstest/typescript_python.ts
 ```

-### Dart.io vs Dart.web E2E matrix
+### Dart.io와 Dart.web E2E 매트릭스

-The `Dart` column above refers to the Dart VM/IO client. `Dart.web` is a separate axis: a browser WS client only — TCP and any server role are not possible in the browser, so those cells are `N/A`. WSS is `Deferred` because there is no automation for trusting the self-signed test certificate in a browser.
+위 표의 `Dart` 열은 Dart VM/IO client를 뜻한다. `Dart.web`은 별도 축이다. 브라우저 WS client만 가능하며, 브라우저에서는 TCP와 server 역할이 불가능하므로 해당 cell은 `N/A`다. WSS는 브라우저에서 self-signed test certificate 신뢰를 자동화하지 않았기 때문에 `Deferred`다.

 | Server | Dart.io TCP | Dart.io WS | Dart.io TLS TCP | Dart.io WSS | Dart.web WS | Dart.web WSS | Dart.web TCP |
 |---|---|---|---|---|---|---|---|
@ -319,7 +319,7 @@ The `Dart` column above refers to the Dart VM/IO client. `Dart.web` is a separat
 | Python | Covered | Covered | Covered | Covered | Covered | Deferred | N/A |
 | TypeScript | Covered | Covered | Covered | Covered | Covered | Deferred | N/A |

-Each Dart.web cell is exercised by a server-language runner that boots its WS server, launches `dart test -p chrome` against the matching browser test file, and asserts the send-push and request-response scenarios:
+각 Dart.web cell은 server-language runner가 해당 WS server를 띄우고, matching browser test file에 대해 `dart test -p chrome`을 실행하며, send-push와 request-response 시나리오를 검증한다.

 ```bash
 cd dart && dart run crosstest/dart_web.dart
@ -331,13 +331,13 @@ cd typescript && ./node_modules/.bin/tsx crosstest/typescript_dart_web.ts

 ---

-## Work Context
+## 작업 맥락

-Before making code or protocol changes, check the project rules in [agent-ops/rules/project/rules.md](agent-ops/rules/project/rules.md) and any matching domain rule listed there. The active roadmap window is in [agent-roadmap/current.md](agent-roadmap/current.md).
+코드나 프로토콜을 변경하기 전에 [agent-ops/rules/project/rules.md](agent-ops/rules/project/rules.md)의 프로젝트 규칙과 해당 경로의 domain rule을 확인한다. 활성 로드맵 창은 [agent-roadmap/current.md](agent-roadmap/current.md)에 있다.

-Stabilization boundaries:
+안정화 경계는 다음과 같다.

- Keep protocol `0.1` behavior stable unless compatibility work is explicitly requested.
- Maintenance-mode work may include bug fixes, documentation corrections, test hardening, and compatibility-preserving implementation fixes.
- Resume C#/Swift, package registry release, or protocol/API change work only when there is concrete consumer demand, a compatibility plan, and a passing full validation matrix.
- Do not connect external CI/CD runners from this repository until the parent `../oto` workflow is decided.
+- 명시적인 호환성 작업 요청이 없으면 프로토콜 `0.1` 동작을 안정적으로 유지한다.
+- 유지보수 모드 작업에는 bug fix, 문서 정정, 테스트 강화, 호환성을 유지하는 구현 수정이 포함될 수 있다.
+- C#/Swift, package registry release, protocol/API 변경 작업은 구체적인 소비자 수요, 호환성 계획, 전체 검증 매트릭스 통과 조건이 있을 때 재개한다.
+- 상위 `../oto` workflow가 결정되기 전까지 이 저장소에서 외부 CI/CD runner를 직접 연결하지 않는다.