ESLint 文档站 Language Switcher 组件解析多语言站点的数据驱动切换方案【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint本指南以 ESLint 官方文档站docs site的 Language Switcher 组件为对象完整拆解它的模板结构、站点数据配置、客户端交互逻辑与无障碍降级方案。读完本文你将理解 ESLint 文档站如何通过一份 YAML 站点清单 一个通用select下拉框实现多语言文档站之间的无缝跳转并能将其复用到自己的多语言静态文档站点中。Language Switcher语言切换器是 ESLint 文档站中的一个小型可复用组件它以组件库component library的形式被收录在 docs/src/library/language-switcher.md 中。该页面本身仅是一条组件引用记录真正的技术实体是它所引用的 组件模板以及驱动它的站点数据、页脚接入点和前端脚本。本文将以这条组件库条目为主线逐层展开其实现细节。一、组件定位它在哪里、何时出现Language Switcher 是 ESLint 文档站站点级site-wideUI 的一部分并非每个内容页面内联的独立元素而是被复用进两类页脚全站页脚 site-footer.html在.content-container中依次引入social-icons.html、theme-switcher.html与language-switcher.html文档区页脚 docs-footer.html在.docs-switchers容器内并排引入theme-switcher.html与language-switcher.html。也就是说用户无论浏览 ESLint 官网首页还是具体文档页面都能在页脚找到切换语言入口。与它同属组件库的还有 Theme Switcher明暗主题切换和 Version Switcher文档版本切换三者共享同一套switcher交互模式和视觉语言但职责不同Language Switcher 负责在不同语言的 ESLint 文档站点之间跳转。从组件库的组织方式看docs/src/library/library.json 将整个组件库页面统一挂载到/component-library/{{ page.fileSlug }}.html因此该文档实际渲染后对应/component-library/language-switcher.html组件展示页。二、组件模板结构渐进增强与无障碍基础组件本体位于 docs/src/_includes/components/language-switcher.html其结构分为三层值得逐行解读div classlanguage-switcher a href/languages/ classswitcher-fallback{{ site.footer.language_switcher.change_language }}/a div hidden roleregion classswitcher switcher--language aria-labelledbylanguage-switcher-label idlanguage-switcher span idlanguage-switcher-label hidden{{ site.footer.language_switcher.title }}/span div classinfobox visually-hidden idlanguage-infobox {{ site.footer.language_switcher.description }} /div label classswitcher__label forlanguage-select span classlabel__text {{ site.footer.language_switcher.language }} /span /label select namelanguage selector idlanguage-select aria-describedbylanguage-infobox classc-custom-select switcher__select {% for key, other_site in sites %} option value{{ other_site.language.code }} >language: code: zh-hans # 语言代码作为 option value 与选中判断依据 flag: # 显示在选项文本中的国旗 emoji name: 简体中文 # 显示在选项文本中的语言名称 locale: zh-hans # 站点 locale与 BCP 47 风格的区域标识一致 hostname: zh-hans.eslint.org # 站点主机名参与跳转 URL 的拼接模板中对site当前站点与other_site候选站点的对比逻辑如下{% for key, other_site in sites %}遍历全部站点为每个站点生成一个option{% if site.language.codeother_site.language.code %}selected{% endif %}当前站点对应选项自动选中选项文本为旗帜 语言名称并依据模板条件为其他语言选项或 latest 分支下所有选项追加(最新)标识其中的最新文案来自other_site.footer.language_switcher.latest。这种一站点一 YAML的数据组织方式意味着新增一种语言只需在sites目录添加对应的 YAML 文件并声明上述字段组件模板无需任何改动即可自动生成新选项这正是该组件可扩展性的来源。四、多语言文案的 i18nfooter.language_switcher 字段组件内所有可见文案都不写死在模板中而是通过site.footer.language_switcher.*从各站点 YAML 中读取。以简体中文站为例zh-hans.ymllanguage_switcher: title: 语言切换 description: 切换到你所选择语言版本对应的 ESLint 网站。 change_language: 更改语言 language: 语言 latest: 最新对应到模板中的使用点change_language→ 无 JS 回退链接的锚文本更改语言title→ 区域标题供aria-labelledby引用description→#language-infobox内的功能说明供aria-describedby引用language→label的文本语言latest→ 选项末尾的最新版本标识。这一设计的价值在于组件模板本身是语言无关的各语言站只需维护自己的 YAML即可获得完全本地化的界面文案而英文站en.yml同样在footer.language_switcher下维护英文对应词条。五、客户端交互逻辑一次 change 一次跳转模板只是静态骨架真正的切换行为由 docs/src/assets/js/main.js 中的一个独立 IIFE 驱动。其逻辑非常精简(function () { var switchers document.querySelectorAll(.switcher), fallbacks document.querySelectorAll(.switcher-fallback); if (fallbacks ! null) { fallbacks.forEach(el { el.setAttribute(hidden, ); }); } if (switchers ! null) { switchers.forEach(element { element.removeAttribute(hidden); const select element.querySelector(select); select.addEventListener(change, function () { var selected this.options[this.selectedIndex]; url selected.getAttribute(data-url); window.location.href url; }); }); } })();该脚本对所有带有.switcher类的元素统一生效因此 Language Switcher、Theme Switcher 等组件共享同一套激活流程隐藏回退链接将所有.switcher-fallback元素置为hidden——既然 JS 可用就不需要再展示普通链接激活切换器移除.switcher上的hidden属性让下拉框对用户可见绑定跳转监听select的change事件取当前选中项this.options[this.selectedIndex]的data-url直接赋值给window.location.href完成整页跳转。由此可以确认一个关键事实切换语言是一次完整的跨站页面导航而非 SPA 内的路由切换——URL 会指向另一个语言站点如zh-hans.eslint.org上对应页面的最新文档地址。从源码结构看跳转目标 URL 统一由模板按规则https://{{ other_site.hostname }}/docs/latest{{ page.url | prettyURL }}拼接其中prettyURL是模板过滤器负责将页面地址规整为无扩展名的友好形式从而保证用户在不同语言站点间切换时停留在语义相同的页面。六、样式与布局language-switcher.scss组件的视觉样式集中在 docs/src/assets/scss/components/language-switcher.scss 中并被 styles.scss 引入与整站样式体系保持一致。核心样式规则如下.switcher--language使用 Flex 布局并允许换行flex-wrap: wrap子项间距为0.25rem 0.5rem默认居中显示在min-width: 800px的媒体查询下改为左对齐justify-content: flex-start.switcher--language .label__textflex: 1 0 10ch保证语言标签占据稳定宽度.switcher--language .switcher__selectflex: 1 0 12rem保证下拉框有最小宽度在max-width: 799px窄屏时进一步限制为max-width: 250px避免撑破小屏布局.language-switcherdisplay: inline-flex使整个切换器在页脚中作为行内弹性元素与其他组件主题切换器、社交图标并排。这些规则与组件模板中的switcher__select、c-custom-select等类协同工作使下拉框在桌面与移动端都有稳定可用的尺寸。七、无 JS 降级与语言列表页当 JavaScript 被禁用或加载失败时.switcher保持hidden用户看到的是.switcher-fallback链接更改语言指向/languages/语言选择页。该页面由 docs/src/pages/languages.md 定义其正文部分通过 languages-list.html 渲染所有语言ul classlanguages-list {%- for language in languages.items -%} li lang{{ language.code }}a href{{ language.url }} {% if config.lang language.code %} aria-currenttrue {% endif %}span classflag{{ language.flag }}/span {{ language.name }}/a/li {%- endfor -%} /ul该列表同样由数据驱动并为当前语言项标记aria-currenttrue帮助辅助技术识别用户当前所在语言。由此形成完整的降级链路有 JS → 页脚下拉框快速切换无 JS → 更改语言链接跳转到/languages/页面的语言列表两种路径都能完成语言切换且都保留了无障碍语义lang属性、aria-current。八、无障碍设计要点汇总从模板与脚本中可以提炼出该组件在无障碍方面的几个实践点语义化控件使用原生select而非自定义模拟下拉天然支持键盘操作区域标注roleregionaria-labelledby明确声明切换区域的用途关联说明aria-describedbylanguage-infobox将隐藏的#language-infobox说明与下拉框关联屏幕阅读器会朗读功能描述显式 labellabel forlanguage-select建立控件与文案的关联隐藏内容可读hidden属性、.visually-hidden两种隐藏方式并用——前者用于真正不可用的 UI后者用于视觉隐藏但保持可读的辅助说明降级可访问无 JS 时回退为普通链接功能不丢失。九、如何将语言切换器复用到自己的文档站结合以上分析若要在一个多语言静态文档站中复刻该组件需要的最小实现包含四部分站点清单仿照 docs/src/_data/sites/en.yml 与 docs/src/_data/sites/zh-hans.yml为每种语言维护language.code、language.flag、language.name、hostname等字段并按同页面、同版本latest约定拼接跨站 URL模板复制 language-switcher.html 的回退链接 hidden 区域 数据驱动select三段结构保证无 JS 可用交互脚本采用 main.js 中查询.switcher→ 移除hidden→ 监听change→ 读取data-url跳转的最小脚本并注意为页面同时存在多个 switcher 组件的情况保留通用性样式与文案引入 language-switcher.scss 的 Flex 布局规则并将所有可见文案放入各语言的footer.language_switcher配置保持模板语言无关。十、小结ESLint 文档站的 Language Switcher 是一个典型的小而完整的站点组件模板层通过 language-switcher.html 定义结构与渐进增强策略数据层通过 sites 目录 的 YAML 清单驱动选项生成与文案本地化行为层由 main.js 中十余行代码统一激活样式层由 language-switcher.scss 保证跨屏可用。它的核心价值在于把语言站点清单与切换交互彻底解耦新增语言只需改数据、不改代码同时以hidden/回退链接的双轨设计兼顾了无 JS 场景与无障碍体验——这套思路对于任何多语言文档站点都具备直接的借鉴意义。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESLint 文档站 Language Switcher 组件解析：多语言站点的数据驱动切换方案
ESLint 文档站 Language Switcher 组件解析多语言站点的数据驱动切换方案【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint本指南以 ESLint 官方文档站docs site的 Language Switcher 组件为对象完整拆解它的模板结构、站点数据配置、客户端交互逻辑与无障碍降级方案。读完本文你将理解 ESLint 文档站如何通过一份 YAML 站点清单 一个通用select下拉框实现多语言文档站之间的无缝跳转并能将其复用到自己的多语言静态文档站点中。Language Switcher语言切换器是 ESLint 文档站中的一个小型可复用组件它以组件库component library的形式被收录在 docs/src/library/language-switcher.md 中。该页面本身仅是一条组件引用记录真正的技术实体是它所引用的 组件模板以及驱动它的站点数据、页脚接入点和前端脚本。本文将以这条组件库条目为主线逐层展开其实现细节。一、组件定位它在哪里、何时出现Language Switcher 是 ESLint 文档站站点级site-wideUI 的一部分并非每个内容页面内联的独立元素而是被复用进两类页脚全站页脚 site-footer.html在.content-container中依次引入social-icons.html、theme-switcher.html与language-switcher.html文档区页脚 docs-footer.html在.docs-switchers容器内并排引入theme-switcher.html与language-switcher.html。也就是说用户无论浏览 ESLint 官网首页还是具体文档页面都能在页脚找到切换语言入口。与它同属组件库的还有 Theme Switcher明暗主题切换和 Version Switcher文档版本切换三者共享同一套switcher交互模式和视觉语言但职责不同Language Switcher 负责在不同语言的 ESLint 文档站点之间跳转。从组件库的组织方式看docs/src/library/library.json 将整个组件库页面统一挂载到/component-library/{{ page.fileSlug }}.html因此该文档实际渲染后对应/component-library/language-switcher.html组件展示页。二、组件模板结构渐进增强与无障碍基础组件本体位于 docs/src/_includes/components/language-switcher.html其结构分为三层值得逐行解读div classlanguage-switcher a href/languages/ classswitcher-fallback{{ site.footer.language_switcher.change_language }}/a div hidden roleregion classswitcher switcher--language aria-labelledbylanguage-switcher-label idlanguage-switcher span idlanguage-switcher-label hidden{{ site.footer.language_switcher.title }}/span div classinfobox visually-hidden idlanguage-infobox {{ site.footer.language_switcher.description }} /div label classswitcher__label forlanguage-select span classlabel__text {{ site.footer.language_switcher.language }} /span /label select namelanguage selector idlanguage-select aria-describedbylanguage-infobox classc-custom-select switcher__select {% for key, other_site in sites %} option value{{ other_site.language.code }} >language: code: zh-hans # 语言代码作为 option value 与选中判断依据 flag: # 显示在选项文本中的国旗 emoji name: 简体中文 # 显示在选项文本中的语言名称 locale: zh-hans # 站点 locale与 BCP 47 风格的区域标识一致 hostname: zh-hans.eslint.org # 站点主机名参与跳转 URL 的拼接模板中对site当前站点与other_site候选站点的对比逻辑如下{% for key, other_site in sites %}遍历全部站点为每个站点生成一个option{% if site.language.codeother_site.language.code %}selected{% endif %}当前站点对应选项自动选中选项文本为旗帜 语言名称并依据模板条件为其他语言选项或 latest 分支下所有选项追加(最新)标识其中的最新文案来自other_site.footer.language_switcher.latest。这种一站点一 YAML的数据组织方式意味着新增一种语言只需在sites目录添加对应的 YAML 文件并声明上述字段组件模板无需任何改动即可自动生成新选项这正是该组件可扩展性的来源。四、多语言文案的 i18nfooter.language_switcher 字段组件内所有可见文案都不写死在模板中而是通过site.footer.language_switcher.*从各站点 YAML 中读取。以简体中文站为例zh-hans.ymllanguage_switcher: title: 语言切换 description: 切换到你所选择语言版本对应的 ESLint 网站。 change_language: 更改语言 language: 语言 latest: 最新对应到模板中的使用点change_language→ 无 JS 回退链接的锚文本更改语言title→ 区域标题供aria-labelledby引用description→#language-infobox内的功能说明供aria-describedby引用language→label的文本语言latest→ 选项末尾的最新版本标识。这一设计的价值在于组件模板本身是语言无关的各语言站只需维护自己的 YAML即可获得完全本地化的界面文案而英文站en.yml同样在footer.language_switcher下维护英文对应词条。五、客户端交互逻辑一次 change 一次跳转模板只是静态骨架真正的切换行为由 docs/src/assets/js/main.js 中的一个独立 IIFE 驱动。其逻辑非常精简(function () { var switchers document.querySelectorAll(.switcher), fallbacks document.querySelectorAll(.switcher-fallback); if (fallbacks ! null) { fallbacks.forEach(el { el.setAttribute(hidden, ); }); } if (switchers ! null) { switchers.forEach(element { element.removeAttribute(hidden); const select element.querySelector(select); select.addEventListener(change, function () { var selected this.options[this.selectedIndex]; url selected.getAttribute(data-url); window.location.href url; }); }); } })();该脚本对所有带有.switcher类的元素统一生效因此 Language Switcher、Theme Switcher 等组件共享同一套激活流程隐藏回退链接将所有.switcher-fallback元素置为hidden——既然 JS 可用就不需要再展示普通链接激活切换器移除.switcher上的hidden属性让下拉框对用户可见绑定跳转监听select的change事件取当前选中项this.options[this.selectedIndex]的data-url直接赋值给window.location.href完成整页跳转。由此可以确认一个关键事实切换语言是一次完整的跨站页面导航而非 SPA 内的路由切换——URL 会指向另一个语言站点如zh-hans.eslint.org上对应页面的最新文档地址。从源码结构看跳转目标 URL 统一由模板按规则https://{{ other_site.hostname }}/docs/latest{{ page.url | prettyURL }}拼接其中prettyURL是模板过滤器负责将页面地址规整为无扩展名的友好形式从而保证用户在不同语言站点间切换时停留在语义相同的页面。六、样式与布局language-switcher.scss组件的视觉样式集中在 docs/src/assets/scss/components/language-switcher.scss 中并被 styles.scss 引入与整站样式体系保持一致。核心样式规则如下.switcher--language使用 Flex 布局并允许换行flex-wrap: wrap子项间距为0.25rem 0.5rem默认居中显示在min-width: 800px的媒体查询下改为左对齐justify-content: flex-start.switcher--language .label__textflex: 1 0 10ch保证语言标签占据稳定宽度.switcher--language .switcher__selectflex: 1 0 12rem保证下拉框有最小宽度在max-width: 799px窄屏时进一步限制为max-width: 250px避免撑破小屏布局.language-switcherdisplay: inline-flex使整个切换器在页脚中作为行内弹性元素与其他组件主题切换器、社交图标并排。这些规则与组件模板中的switcher__select、c-custom-select等类协同工作使下拉框在桌面与移动端都有稳定可用的尺寸。七、无 JS 降级与语言列表页当 JavaScript 被禁用或加载失败时.switcher保持hidden用户看到的是.switcher-fallback链接更改语言指向/languages/语言选择页。该页面由 docs/src/pages/languages.md 定义其正文部分通过 languages-list.html 渲染所有语言ul classlanguages-list {%- for language in languages.items -%} li lang{{ language.code }}a href{{ language.url }} {% if config.lang language.code %} aria-currenttrue {% endif %}span classflag{{ language.flag }}/span {{ language.name }}/a/li {%- endfor -%} /ul该列表同样由数据驱动并为当前语言项标记aria-currenttrue帮助辅助技术识别用户当前所在语言。由此形成完整的降级链路有 JS → 页脚下拉框快速切换无 JS → 更改语言链接跳转到/languages/页面的语言列表两种路径都能完成语言切换且都保留了无障碍语义lang属性、aria-current。八、无障碍设计要点汇总从模板与脚本中可以提炼出该组件在无障碍方面的几个实践点语义化控件使用原生select而非自定义模拟下拉天然支持键盘操作区域标注roleregionaria-labelledby明确声明切换区域的用途关联说明aria-describedbylanguage-infobox将隐藏的#language-infobox说明与下拉框关联屏幕阅读器会朗读功能描述显式 labellabel forlanguage-select建立控件与文案的关联隐藏内容可读hidden属性、.visually-hidden两种隐藏方式并用——前者用于真正不可用的 UI后者用于视觉隐藏但保持可读的辅助说明降级可访问无 JS 时回退为普通链接功能不丢失。九、如何将语言切换器复用到自己的文档站结合以上分析若要在一个多语言静态文档站中复刻该组件需要的最小实现包含四部分站点清单仿照 docs/src/_data/sites/en.yml 与 docs/src/_data/sites/zh-hans.yml为每种语言维护language.code、language.flag、language.name、hostname等字段并按同页面、同版本latest约定拼接跨站 URL模板复制 language-switcher.html 的回退链接 hidden 区域 数据驱动select三段结构保证无 JS 可用交互脚本采用 main.js 中查询.switcher→ 移除hidden→ 监听change→ 读取data-url跳转的最小脚本并注意为页面同时存在多个 switcher 组件的情况保留通用性样式与文案引入 language-switcher.scss 的 Flex 布局规则并将所有可见文案放入各语言的footer.language_switcher配置保持模板语言无关。十、小结ESLint 文档站的 Language Switcher 是一个典型的小而完整的站点组件模板层通过 language-switcher.html 定义结构与渐进增强策略数据层通过 sites 目录 的 YAML 清单驱动选项生成与文案本地化行为层由 main.js 中十余行代码统一激活样式层由 language-switcher.scss 保证跨屏可用。它的核心价值在于把语言站点清单与切换交互彻底解耦新增语言只需改数据、不改代码同时以hidden/回退链接的双轨设计兼顾了无 JS 场景与无障碍体验——这套思路对于任何多语言文档站点都具备直接的借鉴意义。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考