From 4abae396e522e712292f8cce3983c7f27c3c3773 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Wed, 3 Sep 2025 06:56:43 +0900 Subject: [PATCH 1/5] docs: translate SSG documentation comments to English --- website/.env.example | 3 ++- website/src/components/ui/HtmlContent.tsx | 2 +- website/src/components/ui/genPath.ts | 6 ++--- website/src/components/ui/type2href.ts | 6 ++--- website/src/globals.css | 6 ++--- website/src/index.tsx | 4 +-- website/src/types/model.ts | 10 +++---- website/src/utils/flattenDocs.test.ts | 18 ++++++------- website/src/utils/flattenDocs.ts | 14 +++++----- website/src/utils/isPageOfKind.test.ts | 18 ++++++------- website/src/utils/isPageOfKind.ts | 8 +++--- website/src/utils/translationStatus.test.ts | 30 ++++++++++----------- website/src/utils/translationStatus.ts | 26 +++++++++--------- website/translation-status.schema.json | 8 +++--- 14 files changed, 81 insertions(+), 78 deletions(-) diff --git a/website/.env.example b/website/.env.example index 5e5f0d65a..089a2d5e3 100644 --- a/website/.env.example +++ b/website/.env.example @@ -1 +1,2 @@ -VITE_LISTEN_ALL_ADDRESSES=true # 開発用にViteが全てのアドレスでlistenするかどうか +# Whether Vite should listen on all addresses for development. +VITE_LISTEN_ALL_ADDRESSES=true diff --git a/website/src/components/ui/HtmlContent.tsx b/website/src/components/ui/HtmlContent.tsx index d4544a7df..03434dbb2 100644 --- a/website/src/components/ui/HtmlContent.tsx +++ b/website/src/components/ui/HtmlContent.tsx @@ -23,7 +23,7 @@ export const HtmlContent: FC = ({ html }) => { "[&_pre_code]:block", "[&_pre_code]:w-full", ])} - // biome-ignore lint/security/noDangerouslySetInnerHtml: typst-docsで生成されたHTMLを表示する + // biome-ignore lint/security/noDangerouslySetInnerHtml: Displaying HTML generated by typst-docs. dangerouslySetInnerHTML={{ __html: html }} /> ); diff --git a/website/src/components/ui/genPath.ts b/website/src/components/ui/genPath.ts index 10de3b820..1b8493efe 100644 --- a/website/src/components/ui/genPath.ts +++ b/website/src/components/ui/genPath.ts @@ -1,10 +1,10 @@ import type { Func } from "../../types/model"; /** - * pathを連結する + * Concatenates path segments. * - * @param item - Func - * @returns - 連結されたpath + * @param item - A Func object + * @returns - The concatenated path string */ export const genPath = (item: Func): string => { return item.path.map((s) => `${s}.`).join(""); diff --git a/website/src/components/ui/type2href.ts b/website/src/components/ui/type2href.ts index d75f8dde2..8440a65a4 100644 --- a/website/src/components/ui/type2href.ts +++ b/website/src/components/ui/type2href.ts @@ -1,8 +1,8 @@ /** - * 型名からリンクを取得する + * Retrieve a link from a type name. * - * @param parameterType 型名 - * @returns リンク + * @param parameterType The type name. + * @returns The link. */ export const type2href = (parameterType: string): string | null => { const foundationSet = new Set([ diff --git a/website/src/globals.css b/website/src/globals.css index f73d927cd..742c9ee18 100644 --- a/website/src/globals.css +++ b/website/src/globals.css @@ -68,13 +68,13 @@ samp { @apply pt-4; } -/* Alpine.jsのx-cloak属性を持つ要素を非表示にする */ +/* Hide elements with the x-cloak attribute from Alpine.js */ [x-cloak] { display: none !important; visibility: hidden; } -/* Inline codeのスタイルをGitHub風にする */ +/* Style inline code blocks with GitHub-style appearance */ .prose :not(pre) > code { background-color: rgba(175, 184, 193, 0.2); font-size: 0.875em; @@ -91,7 +91,7 @@ samp { } } -/* Code blockをMonokai風にする */ +/* Style code blocks with Monokai theme */ pre code span.typ-comment { color: #88846f; } diff --git a/website/src/index.tsx b/website/src/index.tsx index 5312e595f..54bbbad7f 100644 --- a/website/src/index.tsx +++ b/website/src/index.tsx @@ -16,13 +16,13 @@ import { isPageOfKind } from "./utils/isPageOfKind"; import { removeBasePath } from "./utils/path"; import { registerRoutes } from "./utils/translationStatus"; -// typst-docsが生成したドキュメント +// Documentation generated by typst-docs. import docsJson from "../../docs.json"; const docs = docsJson as unknown as Page[]; const [flattenedPages, pagePaths] = flattenDocs(docs); -// 未知のページを未翻訳として登録する +// Register unknown pages as untranslated. const allRoutes = flattenedPages.map((page) => page.route); registerRoutes(allRoutes); diff --git a/website/src/types/model.ts b/website/src/types/model.ts index c1433e9ab..aad668d48 100644 --- a/website/src/types/model.ts +++ b/website/src/types/model.ts @@ -1,8 +1,8 @@ -// docs.jsonの型 -// cf. docs/src/model.rs +// Type definitions for `docs.json`. +// Reference: `docs/src/model.rs` /** - * ページ情報 + * Page information. */ export type Page = { route: string; @@ -15,7 +15,7 @@ export type Page = { }; /** - * アウトライン情報 + * Outline information. */ export type OutlineItem = { id: string; @@ -24,7 +24,7 @@ export type OutlineItem = { }; /** - * 本文情報 + * Body content information. */ export type Body = | HtmlBody diff --git a/website/src/utils/flattenDocs.test.ts b/website/src/utils/flattenDocs.test.ts index 4b356ad1c..1b31031c6 100644 --- a/website/src/utils/flattenDocs.test.ts +++ b/website/src/utils/flattenDocs.test.ts @@ -20,14 +20,14 @@ describe("flattenDocs", () => { children, }); - it("空の配列を渡すと空の結果を返す", () => { + it("should return an empty result when given an empty array", () => { const [flattenedPages, pagePaths] = flattenDocs([]); expect(flattenedPages).toEqual([]); expect(pagePaths).toEqual([]); }); - it("子を持たない単一ページを平坦化する", () => { + it("should flatten a single page with no children", () => { const page = createMockPage("/docs/", "Documentation"); const [flattenedPages, pagePaths] = flattenDocs([page]); @@ -35,7 +35,7 @@ describe("flattenDocs", () => { expect(pagePaths).toEqual([[page]]); }); - it("複数の子を持たないページを平坦化する", () => { + it("should flatten multiple pages with no children", () => { const page1 = createMockPage("/docs/", "Documentation"); const page2 = createMockPage("/tutorial/", "Tutorial"); const [flattenedPages, pagePaths] = flattenDocs([page1, page2]); @@ -44,7 +44,7 @@ describe("flattenDocs", () => { expect(pagePaths).toEqual([[page1], [page2]]); }); - it("子を持つページを平坦化する", () => { + it("should flatten a page with children", () => { const childPage = createMockPage("/docs/tutorial/", "Tutorial"); const parentPage = createMockPage("/docs/", "Documentation", [childPage]); const [flattenedPages, pagePaths] = flattenDocs([parentPage]); @@ -53,7 +53,7 @@ describe("flattenDocs", () => { expect(pagePaths).toEqual([[parentPage], [parentPage, childPage]]); }); - it("複数階層のページを平坦化する", () => { + it("should flatten pages with multiple levels of children", () => { const grandChildPage = createMockPage("/docs/tutorial/basics/", "Basics"); const childPage = createMockPage("/docs/tutorial/", "Tutorial", [ grandChildPage, @@ -69,7 +69,7 @@ describe("flattenDocs", () => { ]); }); - it("複数の子を持つページを平坦化する", () => { + it("should flatten a page with multiple children", () => { const child1 = createMockPage("/docs/tutorial/", "Tutorial"); const child2 = createMockPage("/docs/reference/", "Reference"); const parentPage = createMockPage("/docs/", "Documentation", [ @@ -86,7 +86,7 @@ describe("flattenDocs", () => { ]); }); - it("複雑な階層構造を平坦化する", () => { + it("should flatten a complex hierarchical structure", () => { // docs/ // ├── tutorial/ // │ ├── basics/ @@ -130,7 +130,7 @@ describe("flattenDocs", () => { ]); }); - it("複数のルートページを持つ階層構造を平坦化する", () => { + it("should flatten a hierarchical structure with multiple root pages", () => { const tutorialChild = createMockPage("/tutorial/basics/", "Basics"); const tutorial = createMockPage("/tutorial/", "Tutorial", [tutorialChild]); @@ -148,7 +148,7 @@ describe("flattenDocs", () => { ]); }); - it("パス情報が正しく設定される", () => { + it("should correctly set path information", () => { const grandChild = createMockPage("/a/b/c/", "C"); const child = createMockPage("/a/b/", "B", [grandChild]); const parent = createMockPage("/a/", "A", [child]); diff --git a/website/src/utils/flattenDocs.ts b/website/src/utils/flattenDocs.ts index 542f6edd4..9c1c9f6db 100644 --- a/website/src/utils/flattenDocs.ts +++ b/website/src/utils/flattenDocs.ts @@ -1,15 +1,17 @@ import type { Page } from "../types/model"; /** - * ドキュメントの階層構造を平坦化する - * パンくずリストと前後のページ情報を取得するために使用する + * Flattens the hierarchical structure of documents. + * Used to retrieve breadcrumb navigation and previous/next page information. * - * @param docs ページ情報の配列 - * @returns [平坦化されたページ情報のリスト, ページ情報のパス情報] + * @param docs An array of page objects containing document information. + * @returns A tuple containing: + * - A flattened list of page objects + * - An array of arrays representing the path information for each page object */ export const flattenDocs = (docs: Page[]): [Page[], Page[][]] => { - const flattenedPages: Page[] = []; // 平坦化されたページ情報のリスト - const pagePaths: Page[][] = []; // ページ情報[i]のパス情報 + const flattenedPages: Page[] = []; // List to store flattened page objects. + const pagePaths: Page[][] = []; // Path information for each page object [i]. const _flattenDocs = (page: Page, pagePath: Page[]): void => { flattenedPages.push(page); diff --git a/website/src/utils/isPageOfKind.test.ts b/website/src/utils/isPageOfKind.test.ts index d25c0e379..a5b071c1b 100644 --- a/website/src/utils/isPageOfKind.test.ts +++ b/website/src/utils/isPageOfKind.test.ts @@ -12,7 +12,7 @@ describe("isPageOfKind", () => { children: [], }); - it("htmlページを正しく判定する", () => { + it("correctly identifies HTML pages", () => { const htmlPage: Page = { ...createBasePage(), body: { @@ -29,7 +29,7 @@ describe("isPageOfKind", () => { expect(isPageOfKind(htmlPage, "symbols")).toBe(false); }); - it("funcページを正しく判定する", () => { + it("correctly identifies func pages", () => { const funcPage: Page = { ...createBasePage(), body: { @@ -61,7 +61,7 @@ describe("isPageOfKind", () => { expect(isPageOfKind(funcPage, "symbols")).toBe(false); }); - it("categoryページを正しく判定する", () => { + it("correctly identifies category pages", () => { const categoryPage: Page = { ...createBasePage(), body: { @@ -84,7 +84,7 @@ describe("isPageOfKind", () => { expect(isPageOfKind(categoryPage, "symbols")).toBe(false); }); - it("groupページを正しく判定する", () => { + it("correctly identifies group pages", () => { const groupPage: Page = { ...createBasePage(), body: { @@ -106,7 +106,7 @@ describe("isPageOfKind", () => { expect(isPageOfKind(groupPage, "symbols")).toBe(false); }); - it("typeページを正しく判定する", () => { + it("correctly identifies type pages", () => { const typePage: Page = { ...createBasePage(), body: { @@ -131,7 +131,7 @@ describe("isPageOfKind", () => { expect(isPageOfKind(typePage, "symbols")).toBe(false); }); - it("symbolsページを正しく判定する", () => { + it("correctly identifies symbols pages", () => { const symbolsPage: Page = { ...createBasePage(), body: { @@ -153,7 +153,7 @@ describe("isPageOfKind", () => { expect(isPageOfKind(symbolsPage, "type")).toBe(false); }); - it("型ガードとして正しく動作する", () => { + it("functions correctly as a type guard", () => { const htmlPage: Page = { ...createBasePage(), body: { @@ -194,11 +194,11 @@ describe("isPageOfKind", () => { } if (isPageOfKind(htmlPage, "func")) { - expect.fail("この分岐は実行されるべきではない"); + expect.fail("This branch should never be executed"); } }); - it("複数のページタイプを配列で処理する", () => { + it("handles multiple page types in an array", () => { const pages: Page[] = [ { ...createBasePage(), diff --git a/website/src/utils/isPageOfKind.ts b/website/src/utils/isPageOfKind.ts index fca19be2e..6e896feb8 100644 --- a/website/src/utils/isPageOfKind.ts +++ b/website/src/utils/isPageOfKind.ts @@ -1,11 +1,11 @@ import type { Body, Page } from "../types/model"; /** - * ページの種類を判定するための型ガード関数 + * Type guard function to determine if a page belongs to a specific kind. * - * @param page - 判定するページ - * @param kind - 判定する種類 - * @returns - ページが指定された種類であるかどうか + * @param page - The page to check. + * @param kind - The kind to check against. + * @returns - A type predicate indicating whether the page is of the specified kind. **/ export const isPageOfKind = ( page: Page, diff --git a/website/src/utils/translationStatus.test.ts b/website/src/utils/translationStatus.test.ts index 4d6b92a2d..699ab6f63 100644 --- a/website/src/utils/translationStatus.test.ts +++ b/website/src/utils/translationStatus.test.ts @@ -27,7 +27,7 @@ describe("translationStatus", () => { }); describe("loadTranslationStatus", () => { - it("ファイルが存在する場合にJSONを読み込んで返す", async () => { + it("should read and return JSON when the file exists", async () => { const { loadTranslationStatus } = await import("./translationStatus"); const mockData = { @@ -45,7 +45,7 @@ describe("translationStatus", () => { expect(result).toEqual(mockData); }); - it("ファイルが存在しない場合に空のオブジェクトを返す", async () => { + it("should return an empty object when the file does not exist", async () => { const { loadTranslationStatus } = await import("./translationStatus"); mockFs.existsSync.mockReturnValue(false); @@ -59,7 +59,7 @@ describe("translationStatus", () => { }); describe("saveTranslationStatus", () => { - it("翻訳状態をJSONファイルに保存する", async () => { + it("should save translation status to a JSON file", async () => { const { saveTranslationStatus } = await import("./translationStatus"); const status: TranslationStatusMap = { @@ -87,7 +87,7 @@ describe("translationStatus", () => { mockFs.existsSync.mockReturnValue(true); }); - it("新しいルートを未翻訳として登録する", async () => { + it("should register new routes as untranslated", async () => { const { registerRoutes } = await import("./translationStatus"); const existingStatus = { @@ -108,7 +108,7 @@ describe("translationStatus", () => { expect(savedData["/docs/new-page/"]).toBe("untranslated"); }); - it("既存のルートは変更しない", async () => { + it("should not modify existing routes", async () => { const { registerRoutes } = await import("./translationStatus"); const existingStatus = { @@ -130,7 +130,7 @@ describe("translationStatus", () => { mockFs.existsSync.mockReturnValue(true); }); - it("翻訳進捗率を正しく計算する", async () => { + it("correctly calculates the translation progress rate", async () => { const { calculateTranslationProgressRate } = await import( "./translationStatus" ); @@ -151,7 +151,7 @@ describe("translationStatus", () => { expect(result).toBe(0.625); }); - it("originalページは計算から除外される", async () => { + it("original pages are excluded from calculation", async () => { const { calculateTranslationProgressRate } = await import( "./translationStatus" ); @@ -160,8 +160,8 @@ describe("translationStatus", () => { $schema: "./translation-status.schema.json", "/docs/page1/": "translated", // 1.0 "/docs/page2/": "partially_translated", // 0.5 - "/docs/original1/": "community", // 除外 - "/docs/original2/": "community", // 除外 + "/docs/original1/": "community", // Excluded + "/docs/original2/": "community", // Excluded "/docs/page3/": "untranslated", // 0.0 }; @@ -173,7 +173,7 @@ describe("translationStatus", () => { expect(result).toBe(0.5); }); - it("全てoriginalページの場合は0を返す", async () => { + it("returns 0 when all pages are original", async () => { const { calculateTranslationProgressRate } = await import( "./translationStatus" ); @@ -191,7 +191,7 @@ describe("translationStatus", () => { expect(result).toBe(0); }); - it("ページが存在しない場合は0を返す", async () => { + it("returns 0 when a page does not exist", async () => { const { calculateTranslationProgressRate } = await import( "./translationStatus" ); @@ -207,7 +207,7 @@ describe("translationStatus", () => { expect(result).toBe(0); }); - it("$schemaキーは計算から除外する", async () => { + it("excludes the $schema key from calculation", async () => { const { calculateTranslationProgressRate } = await import( "./translationStatus" ); @@ -226,7 +226,7 @@ describe("translationStatus", () => { }); describe("getTranslationStatus", () => { - it("指定されたルートの翻訳状態を返す", async () => { + it("returns the translation status of the specified route", async () => { const { getTranslationStatus } = await import("./translationStatus"); const status = { @@ -243,7 +243,7 @@ describe("translationStatus", () => { ); }); - it('存在しないルートの場合は"untranslated"を返す', async () => { + it('returns "untranslated" for a non-existent route', async () => { const { getTranslationStatus } = await import("./translationStatus"); const status = { @@ -256,7 +256,7 @@ describe("translationStatus", () => { expect(getTranslationStatus("/docs/nonexistent/")).toBe("untranslated"); }); - it("2回目の呼び出しではキャッシュを使用する", async () => { + it("uses cache for the second and subsequent calls", async () => { vi.resetModules(); const { getTranslationStatus: freshGetTranslationStatus } = await import( "./translationStatus" diff --git a/website/src/utils/translationStatus.ts b/website/src/utils/translationStatus.ts index f7ac4e567..8e7db2922 100644 --- a/website/src/utils/translationStatus.ts +++ b/website/src/utils/translationStatus.ts @@ -17,8 +17,8 @@ const TRANSLATION_STATUS_FILE = path.resolve( ); /** - * ページの翻訳状態を管理しているJSONファイルを読み込む。ファイルが存在しない場合は空のオブジェクトを返す。 - * @returns ページの翻訳状態を示すオブジェクト。 + * Loads the JSON file managing translation status for a page. If the file does not exist, returns an empty object. + * @returns An object representing the translation status of the page. */ export const loadTranslationStatus = (): TranslationStatusMap => { if (fs.existsSync(TRANSLATION_STATUS_FILE)) { @@ -30,8 +30,8 @@ export const loadTranslationStatus = (): TranslationStatusMap => { }; /** - * ページの翻訳状態を管理しているJSONファイルに書き込む。 - * @param status ページの翻訳状態を示すオブジェクト。 + * Writes the page's translation status to the JSON file. + * @param status An object representing the translation status of the page. */ export const saveTranslationStatus = (status: TranslationStatusMap): void => { const json = { @@ -46,8 +46,8 @@ export const saveTranslationStatus = (status: TranslationStatusMap): void => { }; /** - * 新規ページのルートを未翻訳として登録する。既に登録されているルートは無視される。 - * @param routes 登録するページのルートの配列。 + * Registers new page routes as untranslated. Existing routes are ignored. + * @param routes An array of page route paths to register. */ export const registerRoutes = (routes: string[]): void => { const status = loadTranslationStatus(); @@ -66,10 +66,10 @@ export const registerRoutes = (routes: string[]): void => { }; /** - * 翻訳の進捗率を計算する。 - * `translated`は1.0、`partially_translated`は0.5の重みを持つ。 - * `original`は翻訳対象外のため計算から除外される。 - * @returns [0.0, 1.0]の範囲で表される翻訳率 + * Calculates the translation progress rate. + * `translated` has a weight of 1.0, `partially_translated` has a weight of 0.5. + * `original` routes are excluded from calculation as they are not translatable. + * @returns A translation rate between 0.0 and 1.0. */ export const calculateTranslationProgressRate = (): number => { const status = loadTranslationStatus(); @@ -99,9 +99,9 @@ export const calculateTranslationProgressRate = (): number => { let translationStatusCache: TranslationStatusMap | null = null; /** - * 指定されたルートの翻訳状態を取得する。 - * @param route 翻訳状態を取得するページのルート - * @returns 翻訳状態。存在しない場合は"untranslated"を返す。 + * Retrieves the translation status for a specified route. + * @param route The page route for which to retrieve the translation status. + * @returns The translation status, or "untranslated" if the route does not exist. */ export const getTranslationStatus = (route: string): TranslationStatus => { if (translationStatusCache === null) { diff --git a/website/translation-status.schema.json b/website/translation-status.schema.json index d97147349..c3c6b577e 100644 --- a/website/translation-status.schema.json +++ b/website/translation-status.schema.json @@ -1,17 +1,17 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "title": "ページの翻訳状態", - "description": "各ページの翻訳状態を管理するためのJSONファイル", + "title": "Page Translation Status", + "description": "A JSON file for managing the translation status of each page", "type": "object", "properties": { "$schema": { "type": "string", - "description": "このJSONファイルで使用されるJSONスキーマへの参照" + "description": "Reference to the JSON schema used in this file" } }, "additionalProperties": { "type": "string", "enum": ["translated", "partially_translated", "untranslated", "community"], - "description": "ページの翻訳状態" + "description": "The translation status of the page" } } From 1f7fb3cb2f2e77479939ae3ec8e993a14da363da Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Wed, 3 Sep 2025 09:53:25 +0900 Subject: [PATCH 2/5] docs: apply suggestion Co-authored-by: Its-Just-Nans <56606507+Its-Just-Nans@users.noreply.github.com> --- website/src/components/ui/common/SearchWindow.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/components/ui/common/SearchWindow.tsx b/website/src/components/ui/common/SearchWindow.tsx index 06723eaa0..d3186c047 100644 --- a/website/src/components/ui/common/SearchWindow.tsx +++ b/website/src/components/ui/common/SearchWindow.tsx @@ -39,7 +39,7 @@ export const SearchWindow: FC = () => { {!import.meta.env.DEV && (