From 6c9a959760dcdac974f77cd077fbf2dc6856d01a Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Mon, 15 Jun 2026 18:19:47 -0700 Subject: [PATCH] feat(docs): i18n scaffold + Chinese/Japanese pilot (zh-cn, ja) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Starlight i18n: root locale (English at /) + zh-cn + ja, with translated sidebar group labels. Untranslated pages fall back to English with a notice. - Pilot translations (prove quality before full rollout): Guide → Quickstart and Routing, in both zh-cn and ja. Prose + frontmatter translated; code, identifiers, commands, and paths kept verbatim; in-locale links prefixed. - Starlight's built-in UI strings (search, TOC, nav, theme/lang pickers) auto-translate for both locales. Note: sidebar group-label `translations` are keyed by BCP-47 lang tag (`zh-CN`), not the locale key (`zh-cn`). Co-Authored-By: Claude Opus 4.8 (1M context) --- site/astro.config.mjs | 16 +++- site/src/content/docs/ja/guide/quickstart.md | 74 +++++++++++++++++++ site/src/content/docs/ja/guide/routing.md | 74 +++++++++++++++++++ .../content/docs/zh-cn/guide/quickstart.md | 74 +++++++++++++++++++ site/src/content/docs/zh-cn/guide/routing.md | 74 +++++++++++++++++++ 5 files changed, 309 insertions(+), 3 deletions(-) create mode 100644 site/src/content/docs/ja/guide/quickstart.md create mode 100644 site/src/content/docs/ja/guide/routing.md create mode 100644 site/src/content/docs/zh-cn/guide/quickstart.md create mode 100644 site/src/content/docs/zh-cn/guide/routing.md diff --git a/site/astro.config.mjs b/site/astro.config.mjs index b6a54196..d22ff55c 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -10,6 +10,14 @@ export default defineConfig({ integrations: [ starlight({ title: 'Echo', + // English at the root (/guide/…); translations under /zh-cn/… and /ja/…. + // Untranslated pages fall back to English with a notice until translated. + defaultLocale: 'root', + locales: { + root: { label: 'English', lang: 'en' }, + 'zh-cn': { label: '简体中文', lang: 'zh-CN' }, + ja: { label: '日本語', lang: 'ja' }, + }, logo: { light: './src/assets/logo-light.svg', dark: './src/assets/logo-dark.svg', @@ -72,10 +80,12 @@ export default defineConfig({ ], // Autogenerated from the content dirs — new pages appear automatically, // ordered by each page's `sidebar.order` frontmatter. + // Group labels are in the default locale; page entries auto-translate from + // each translated file's frontmatter `title`. sidebar: [ - { label: 'Guide', items: [{ autogenerate: { directory: 'guide' } }] }, - { label: 'Middleware', items: [{ autogenerate: { directory: 'middleware' } }] }, - { label: 'Cookbook', items: [{ autogenerate: { directory: 'cookbook' } }] }, + { label: 'Guide', translations: { 'zh-CN': '指南', ja: 'ガイド' }, items: [{ autogenerate: { directory: 'guide' } }] }, + { label: 'Middleware', translations: { 'zh-CN': '中间件', ja: 'ミドルウェア' }, items: [{ autogenerate: { directory: 'middleware' } }] }, + { label: 'Cookbook', translations: { 'zh-CN': '示例', ja: 'クックブック' }, items: [{ autogenerate: { directory: 'cookbook' } }] }, ], // tune the built-in code theme toward our terminal palette expressiveCode: { themes: ['github-dark', 'github-light'] }, diff --git a/site/src/content/docs/ja/guide/quickstart.md b/site/src/content/docs/ja/guide/quickstart.md new file mode 100644 index 00000000..484c1095 --- /dev/null +++ b/site/src/content/docs/ja/guide/quickstart.md @@ -0,0 +1,74 @@ +--- +title: クイックスタート +description: 本番運用に耐える Echo API を5分以内で構築します。 +sidebar: + order: 1 +--- + +Echo は高性能でミニマルな Go 製 Web フレームワークです。このガイドでは、5分以内でサーバーを起動します。 + +## 要件 + +Echo には **Go 1.25 以降** が必要です。バージョンを確認します： + +```bash +go version +``` + +## インストール + +モジュールを作成して Echo を追加します： + +```bash +go mod init myapp +go get github.com/labstack/echo/v5 +``` + +## Hello, World + +`main.go` を作成します： + +```go +package main + +import ( + "net/http" + + "github.com/labstack/echo/v5" + "github.com/labstack/echo/v5/middleware" +) + +func main() { + e := echo.New() + + e.Use(middleware.RequestLogger()) + e.Use(middleware.Recover()) + + e.GET("/", func(c *echo.Context) error { + return c.JSON(http.StatusOK, map[string]string{"message": "Hello, World!"}) + }) + + if err := e.Start(":1323"); err != nil { + e.Logger.Error("failed to start server", "error", err) + } +} +``` + +実行します： + +```bash +go run main.go +``` + +サーバーは `http://localhost:1323` で起動しています。Echo のルーターは、ルートごとに**動的なメモリ割り当てゼロ**でリクエストをディスパッチします。 + +:::tip[Ask Echo] +お困りですか？右下の **Ask Echo** ボタンを押して +*「JWT 認証を追加するには？」* と質問してください。回答はこのドキュメントから直接得られます。 +::: + +## 次のステップ + +- [ルーティング](/ja/guide/routing/) —— 静的・パラメータ付き・ワイルドカードのルート。 +- [コンテキスト](/ja/guide/context/) —— リクエストごとのリクエスト/レスポンスオブジェクト。 +- [バインディング](/ja/guide/binding/) —— リクエストデータを型付き構造体に解析します。 diff --git a/site/src/content/docs/ja/guide/routing.md b/site/src/content/docs/ja/guide/routing.md new file mode 100644 index 00000000..49891ff0 --- /dev/null +++ b/site/src/content/docs/ja/guide/routing.md @@ -0,0 +1,74 @@ +--- +title: ルーティング +description: Echo のゼロアロケーション基数木で、リクエスト URL をハンドラにマッチさせます。 +sidebar: + order: 3 +--- + +Echo の最適化されたルーターは、基数木（radix tree）を用いてリクエスト URL をハンドラにマッチさせます。**ルートごとに動的なメモリ割り当てはゼロ**で、賢いルート優先順位付けを備えています。 + +## ルートの登録 + +`Echo` インスタンスの HTTP メソッドヘルパーを使います。各ヘルパーはパスパターンと +`HandlerFunc`（`func(c *echo.Context) error`）を受け取り、任意でルートレベルのミドルウェアを指定できます。 + +```go +e := echo.New() + +e.GET("/users/:id", getUser) // named parameter +e.POST("/users", createUser) +e.PUT("/users/:id", updateUser) +e.DELETE("/users/:id", deleteUser) +e.GET("/static/*", serveFiles) // wildcard +``` + +`Any` はサポートされるすべてのメソッドに、`Match` は指定したメソッド集合にハンドラを登録します： + +```go +e.Any("/ping", pong) +e.Match([]string{http.MethodGet, http.MethodPost}, "/form", handleForm) +``` + +## マッチの種類 + +| パターン | 種類 | マッチ例 | +| ---------------- | -------------- | --------------------- | +| `/users/profile` | 静的 | `/users/profile` | +| `/users/:id` | パラメータ | `/users/42` | +| `/static/*` | ワイルドカード | `/static/css/app.css` | + +:::note +優先順位は **静的 → パラメータ → ワイルドカード** です。したがって `/users/profile` は常に +`/users/:id` より優先され、さらにそれは `/users/*` より優先されます。 +::: + +## パスパラメータ + +`c.Param()` でコンテキストから名前付きパラメータを読み取ります（デフォルト値が必要な場合は `c.ParamOr()`）： + +```go +func getUser(c *echo.Context) error { + id := c.Param("id") + return c.String(http.StatusOK, id) +} +``` + +ワイルドカードのセグメントは `*` パラメータとして取得できます： + +```go +e.GET("/files/*", func(c *echo.Context) error { + return c.String(http.StatusOK, c.Param("*")) +}) +``` + +## グループ + +接頭辞とミドルウェアを共有するルートを `e.Group()` でまとめます： + +```go +admin := e.Group("/admin", middleware.BasicAuth(authFn)) +admin.GET("/metrics", metrics) // -> /admin/metrics +admin.GET("/users", listUsers) // -> /admin/users +``` + +グループはネストして、より大きなルートツリーを構成できます。 diff --git a/site/src/content/docs/zh-cn/guide/quickstart.md b/site/src/content/docs/zh-cn/guide/quickstart.md new file mode 100644 index 00000000..36ad5c8e --- /dev/null +++ b/site/src/content/docs/zh-cn/guide/quickstart.md @@ -0,0 +1,74 @@ +--- +title: 快速开始 +description: 在五分钟内构建一个可用于生产的 Echo API。 +sidebar: + order: 1 +--- + +Echo 是一个高性能、极简的 Go Web 框架。本指南将在五分钟内让服务器运行起来。 + +## 环境要求 + +Echo 需要 **Go 1.25 或更高版本**。检查你的版本： + +```bash +go version +``` + +## 安装 + +创建一个模块并添加 Echo： + +```bash +go mod init myapp +go get github.com/labstack/echo/v5 +``` + +## Hello, World + +创建 `main.go`： + +```go +package main + +import ( + "net/http" + + "github.com/labstack/echo/v5" + "github.com/labstack/echo/v5/middleware" +) + +func main() { + e := echo.New() + + e.Use(middleware.RequestLogger()) + e.Use(middleware.Recover()) + + e.GET("/", func(c *echo.Context) error { + return c.JSON(http.StatusOK, map[string]string{"message": "Hello, World!"}) + }) + + if err := e.Start(":1323"); err != nil { + e.Logger.Error("failed to start server", "error", err) + } +} +``` + +运行： + +```bash +go run main.go +``` + +服务器已在 `http://localhost:1323` 上运行。Echo 的路由器在分发请求时**每个路由零动态内存分配**。 + +:::tip[Ask Echo] +遇到问题？点击右下角的 **Ask Echo** 按钮，提问 +*“如何添加 JWT 认证？”*——答案直接来自这些文档。 +::: + +## 下一步 + +- [路由](/zh-cn/guide/routing/) —— 静态、带参数和通配符路由。 +- [上下文](/zh-cn/guide/context/) —— 每个请求的请求/响应对象。 +- [绑定](/zh-cn/guide/binding/) —— 将请求数据解析为类型化的结构体。 diff --git a/site/src/content/docs/zh-cn/guide/routing.md b/site/src/content/docs/zh-cn/guide/routing.md new file mode 100644 index 00000000..cfd9d509 --- /dev/null +++ b/site/src/content/docs/zh-cn/guide/routing.md @@ -0,0 +1,74 @@ +--- +title: 路由 +description: 在 Echo 的零分配基数树上将请求 URL 匹配到处理函数。 +sidebar: + order: 3 +--- + +Echo 优化过的路由器使用基数树（radix tree）将请求 URL 匹配到处理函数，**每个路由零动态内存分配**，并具有智能的路由优先级。 + +## 注册路由 + +在 `Echo` 实例上使用 HTTP 方法辅助函数。每个函数接受一个路径模式和一个 +`HandlerFunc`（`func(c *echo.Context) error`），并可选地附带路由级中间件。 + +```go +e := echo.New() + +e.GET("/users/:id", getUser) // named parameter +e.POST("/users", createUser) +e.PUT("/users/:id", updateUser) +e.DELETE("/users/:id", deleteUser) +e.GET("/static/*", serveFiles) // wildcard +``` + +`Any` 为所有受支持的方法注册处理函数，`Match` 则用于指定的方法集合： + +```go +e.Any("/ping", pong) +e.Match([]string{http.MethodGet, http.MethodPost}, "/form", handleForm) +``` + +## 匹配类型 + +| 模式 | 类型 | 匹配示例 | +| ---------------- | -------- | --------------------- | +| `/users/profile` | 静态 | `/users/profile` | +| `/users/:id` | 参数 | `/users/42` | +| `/static/*` | 通配符 | `/static/css/app.css` | + +:::note +优先级为 **静态 → 参数 → 通配符**，因此 `/users/profile` 始终优先于 +`/users/:id`，而后者又优先于 `/users/*`。 +::: + +## 路径参数 + +使用 `c.Param()` 从上下文读取命名参数（或使用 `c.ParamOr()` 提供默认值）： + +```go +func getUser(c *echo.Context) error { + id := c.Param("id") + return c.String(http.StatusOK, id) +} +``` + +通配符段可通过 `*` 参数获取： + +```go +e.GET("/files/*", func(c *echo.Context) error { + return c.String(http.StatusOK, c.Param("*")) +}) +``` + +## 路由组 + +使用 `e.Group()` 将共享前缀和中间件的路由分组： + +```go +admin := e.Group("/admin", middleware.BasicAuth(authFn)) +admin.GET("/metrics", metrics) // -> /admin/metrics +admin.GET("/users", listUsers) // -> /admin/users +``` + +路由组可以嵌套，以组合更大的路由树。