docs: translate SSG documentation comments to English (typst-jp#283)

Co-authored-by: Its-Just-Nans <[email protected]>
Co-authored-by: Y.D.X. <[email protected]>

Author: 3 people

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

website/src/components/ui/HtmlContent.tsx

@@ -23,7 +23,7 @@ export const HtmlContent: FC<HtmlContentProps> = ({ 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 }}
 		/>
 	);

website/src/components/ui/common/SearchWindow.tsx

@@ -39,7 +39,7 @@ export const SearchWindow: FC = () => {
 			</div>
 			{!import.meta.env.DEV && (
 				<script
-					// biome-ignore lint/security/noDangerouslySetInnerHtml: pagefindで生成されたスクリプトを実行する
+					// biome-ignore lint/security/noDangerouslySetInnerHtml: Execute scripts generated by pagefind.
 					dangerouslySetInnerHTML={{
 						__html: `window.addEventListener('DOMContentLoaded', (event) => {
 	new PagefindUI({ element: "#search", showSubResults: true });

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("");

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([

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;
 }

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);
 

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`
 
 /**
- * ページ情報
+ * Details about a documentation page and its children.
  */
 export type Page = {
 	route: string;
@@ -15,7 +15,7 @@ export type Page = {
 };
 
 /**
- * アウトライン情報
+ * An element in the outline.
  */
 export type OutlineItem = {
 	id: string;
@@ -24,7 +24,7 @@ export type OutlineItem = {
 };
 
 /**
- * 本文情報
+ * Details about the body of a documentation page.
  */
 export type Body =
 	| HtmlBody

website/src/utils/flattenDocs.test.ts

@@ -20,22 +20,22 @@ 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]);
 
 		expect(flattenedPages).toEqual([page]);
 		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]);

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);