Skip to content

docs: add Japanese translations #374

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
milooy merged 1 commit into from
Sep 29, 2025
Merged

docs: add Japanese translations #374

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 82 additions & 1 deletion fundamentals/a11y/.vitepress/config.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,88 @@ export default defineConfig({
ja: {
label: "日本語",
lang: "ja",
themeConfig: { nav: [{ text: "ホーム", link: "/ja" }] }
themeConfig: {
nav: [{ text: "ホーム", link: "/ja/" }],
sidebar: [
{
text: "紹介",
items: [
{ text: "はじめに", link: "/ja/overview" },
{ text: "体験してみる", link: "/ja/playground" },
{ text: "アクセシビリティを守る理由", link: "/ja/why" },
{ text: "主要原則", link: "/ja/principles" }
]
},
{
text: "実践ガイド",
items: [
{
text: "1. 構造を明確にする",
items: [
{
text: "ボタンの中にボタンを入れない",
link: "/ja/structure/button-inside-button"
},
{
text: "テーブル行に直接onClickを付けない",
link: "/ja/structure/table-row-link"
}
]
},
{
text: "2. 意味を正確に伝える",
items: [
{
text: "インタラクティブ要素に名前を付ける",
link: "/ja/semantic/required-label"
},
{
text: "同じ名前の要素には説明を追加する",
link: "/ja/semantic/duplicate-interactive-element"
}
]
},
{
text: "3. 予測可能な動作を作る",
items: [
{
text: "ボタンの役割と動作を一致させる",
link: "/ja/predictability/fake-button"
},
{
text: "入力要素は <form> で包む",
link: "/ja/predictability/form"
}
]
},
{
text: "4. 視覚情報を補完する",
items: [
{
text: "画像とアイコンに適切な代替テキストを提供する",
link: "/ja/alt-text/image-alt"
}
]
}
]
},
{
text: "発展ガイド",
items: [
{
text: "ESLintでアクセシビリティを改善する",
items: [
{ text: "主要ルール紹介", link: "/ja/eslint/rules" },
{
text: "デザインシステムと組み合わせる",
link: "/ja/eslint/design-system"
}
]
}
]
}
]
}
},
"zh-hans": {
label: "简体中文",
Expand Down
135 changes: 135 additions & 0 deletions fundamentals/a11y/ja/alt-text/image-alt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# 画像やアイコンに適切な代替テキストを提供する

画像やアイコンを使うときは、スクリーンリーダー利用者のために適切な代替テキストを提供する必要があります。ただし、すべての画像に代替テキストが必要というわけではありません。このドキュメントでは、いつ・どのように代替テキストを付けるべきかを説明します。

## 代替テキストを提供すべきとき

画像やアイコンが**情報を伝える、または機能を表す**場合は、必ず意味のある代替テキストを付けましょう。画像やアイコンしかない場面では、代替テキストが視覚情報を補う唯一の手段になるため、テキストがないとユーザー体験が大きく損なわれます。

### ❌ 誤った例：意味のあるアイコンに代替テキストがない

次のように代替テキストを空にすると、スクリーンリーダー利用者はこのボタンが何の機能なのか分かりません。

```html
<button>
<img src="search-icon.svg" alt="" />
</button>
```

### ✅ 正しい例：意味のあるアイコンに代替テキストを付ける

```html
<button>
<img src="search-icon.svg" alt="検索" />
</button>
```

## 代替テキストを付けなくてよいとき

### 1. 装飾目的の画像

画像が単なる装飾で、視覚的効果だけを目的としているなら、空の代替テキスト（`alt=""`）を使いましょう。

#### ❌ 誤った例：装飾画像に不要な代替テキスト

スクリーンリーダーがこのテキストを読み上げ、不要な情報となってしまいます。

```html
<img src="divider.png" alt="区切り線" />
```

#### ✅ 正しい例：装飾画像には空のalt属性

```html
<img src="divider.png" alt="" />
```

### 2. 画像の周辺に説明テキストがある場合

画像の近くに十分な説明があるなら、画像側は空の代替テキストを使いましょう。

#### ❌ 誤った例：重複する代替テキスト

次のように周囲に説明があるのに、同じ内容を代替テキストとしても提供すると、スクリーンリーダーでは「新製品スマートフォン 新製品スマートフォン」のように重複して読み上げ、混乱の原因になります。

```html
<figure>
<img src="product.jpg" alt="신제품 스마트폰" />
<figcaption>新製品スマートフォン</figcaption>
</figure>
```

#### ✅ 正しい例：キャプションがある画像では省略

```html
<figure>
<img src="product.jpg" alt="" />
<figcaption>新製品スマートフォン</figcaption>
</figure>
```

### 3. アイコンがテキストと一緒に使われる場合

アイコンがテキストと一緒にボタンやリンクで使われるときは、空の代替テキストを使いましょう。

#### ❌ 誤った例：不要な重複情報

スクリーンリーダーで「削除 アイコン 削除」と重複して読まれてしまい、かえってわかりにくくなります。

```html
<button>
<img src="trash-icon.svg" alt="削除アイコン" />
削除
</button>
```

#### ✅ 正しい例：テキストがあるアイコンでは省略

```html
<button>
<img src="trash-icon.svg" alt="" />
削除
</button>
```

## 効果的な代替テキストを書く

良い代替テキストは短く、明確で、画像の目的に合っている必要があります。以下の原則を参考に、状況に合わせて記述しましょう。

### 1. 明確かつ具体的に書く

代替テキストは、その画像が伝える意味を正確に説明するべきです。あいまいな言葉や抽象的な表現は、ユーザーが画像から得るべき情報を理解しづらくします。

| 区分 | 例 | 説明 |
| ---------- | -------------------- | ------------------------------------------------------ |
| ❌ 悪い例 | "アイコン" | アイコンの用途や機能に関する情報がありません。 |
| ✅ 良い例 | "検索" | アイコンが何を意味するかを明確に伝えます。 |
| ❌ 悪い例 | "グラフ" | このグラフが何を示すのか分かりません。 |
| ✅ 良い例 | "2023年の売上グラフ" | グラフがどのデータを示すかを具体的に説明します。 |

### 2. 不要な語を省く

代替テキストはスクリーンリーダーが読むためのものなので、「アイコン」「ボタン」のような語はたいてい冗長です。スクリーンリーダーは、画像を含む要素の役割（ボタンなど）を既に理解しているため、代替テキストでは情報だけを簡潔に伝えるのが望ましいです。

| 区分 | 例 | 説明 |
| ---------- | ------------- | --------------------------------------------------------------------------------------- |
| ✅ 良い例 | "検索" | |
| ❌ 悪い例 | "検索アイコン" | スクリーンリーダーは「検索、ボタン」と読むため、「アイコン」は重複して不要です。 |
| ✅ 良い例 | "閉じる" | |
| ❌ 悪い例 | "閉じるボタン" | ボタンという役割は既に明らかなので、テキストでは省略したほうがすっきりします。 |

### 3. 画像の目的と文脈を考慮する

同じ画像でも、使われる文脈によって適切な代替テキストは変わり得ます。次のコードで「矢印」という説明は、見た目を述べているだけで、ユーザーにどんな操作が可能かは伝えません。

「前のページへ移動」のような代替テキストは、機能を正確に説明し、ユーザーの期待と実際の動作を一致させます。

```html
<!-- ❌ 誤った例：文脈を考慮しない代替テキスト -->
<img src="arrow.png" alt="矢印" />
<img src="arrow.png" alt="矢印" />

<!-- ✅ 正しい例：文脈に合った代替テキスト -->
<img src="arrow.png" alt="前のページへ移動" />
<img src="arrow.png" alt="次のページへ移動" />
```
Loading
Loading