bootstrap-datepicker 国际化（i18n）完全指南：语言包、自定义翻译与 RTL 布局

bootstrap-datepicker 国际化（i18n）完全指南：语言包、自定义翻译与 RTL 布局

【免费下载链接】bootstrap-datepickerA datepicker for twitter bootstrap (@twbs)项目地址: https://gitcode.com/gh_mirrors/bo/bootstrap-datepicker

bootstrap-datepicker 是 Twitter Bootstrap 生态中广泛使用的 jQuery 日期选择器插件，其国际化能力让开发者可以用几十种语言本地化界面。本文基于仓库 docs/i18n.rst 官方文档，结合 js/bootstrap-datepicker.js 源码与 tests/suites/options.js 测试用例，系统讲解语言包加载、自定义翻译、语言代码回退机制、RTL（从右到左）语言布局以及编码问题的完整解决方案，读完即可在自己的项目里落地多语言日期选择器。

国际化机制概览

bootstrap-datepicker 的 i18n 覆盖两个维度：

1. 界面文案：月份名、星期名（含days/daysShort/daysMin三种粒度）、today（今天）按钮、clear（清除）按钮、视图标题（titleFormat）等；
2. 日期行为：weekStart（每周起始日）、format（日期格式）以及rtl（从右到左布局），这些会直接影响输入框的值格式与日历渲染。

默认语言是英语（"en"），其余语言翻译包统一存放在 js/locales/ 目录，目前仓库内置了 70 余种语言文件（如中文 bootstrap-datepicker.zh-CN.js、日文、阿拉伯文、俄文等），并全部通过$.fn.datepicker.dates注册。使用方式非常简单：在插件主文件之后按需引入对应语言文件，然后通过language选项指定语言代码即可。

引入语言包：两步启用本地化

以简体中文为例，页面上按顺序引入 jQuery、插件主文件与语言文件，再以language: 'zh-CN'初始化：

<script src="jquery.js"></script> <script src="bootstrap-datepicker.js"></script> <script src="js/locales/bootstrap-datepicker.zh-CN.js"></script>

$('.datepicker').datepicker({ language: 'zh-CN' });

语言文件的核心逻辑就是向全局注册表写入翻译对象，例如 bootstrap-datepicker.zh-CN.js：

$.fn.datepicker.dates['zh-CN'] = { days: ["星期日", "星期一", "星期二", "星期三", "星期四", "星期五", "星期六"], daysShort: ["周日", "周一", "周二", "周三", "周四", "周五", "周六"], daysMin: ["日", "一", "二", "三", "四", "五", "六"], months: ["一月", "二月", "三月", "四月", "五月", "六月", "七月", "八月", "九月", "十月", "十一月", "十二月"], monthsShort: ["1月", "2月", "3月", "4月", "5月", "6月", "7月", "8月", "9月", "10月", "11月", "12月"], today: "今天", monthsTitle: "选择月份", clear: "清除", format: "yyyy-mm-dd", titleFormat: "yyyy年mm月", weekStart: 1 };

注意language选项在 docs/options.rst 中定义，默认值为"en"。它指定的语言代码会同时用于月份/星期显示，以及输入框的值格式化与表单提交（即写入 input 的日期字符串也按该语言的format生成）。

语言代码回退机制：de-DE → de → en

从源码看，语言解析并非简单查表，而是带三级回退的：

• js/bootstrap-datepicker.js（_process_options）：先查完整代码（如de-DE），找不到则拆出主语言段（de）再查，仍找不到则回退到默认en；
• js/bootstrap-datepicker.js（opts_from_locale）：初始化时从语言包提取format、rtl、weekStart三个选项合并进最终配置，优先级顺序为defaults < locales <>$.fn.datepicker.dates['en'] = { days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"], daysShort: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"], daysMin: ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"], months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"], monthsShort: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], today: "Today", clear: "Clear", format: "mm/dd/yyyy", titleFormat: "MM yyyy", /* 与 'format' 使用相同语法 */ weekStart: 0 };

  各字段的作用与含义如下：

  字段	用途	说明
  days/daysShort/daysMin	星期名三种粒度	分别对应完整星期名、缩写、单字符/极短形式；daysMin用于表头星期行（见 fillDow），monthsShort用于月份视图（见 fillMonths）
  months/monthsShort	月份名	完整月份名用于formatDate输出与标题；短名用于月份选择视图
  today/clear	底部按钮文案	渲染时若当前语言缺失，会回退到dates['en'].today再回退到空串（见 js/bootstrap-datepicker.js）
  titleFormat	视图切换按钮标题格式	与format同一套占位符语法；缺失时回退到英语titleFormat（见 js/bootstrap-datepicker.js）
  format	日期格式化/解析格式	会被合并进locale_opts（format、rtl、weekStart，见 js/bootstrap-datepicker.js），决定输入框值格式
  weekStart	每周起始日	0（周日）～ 6（周六），同样来自locale_opts

  titleFormat与format使用同一套占位符语法：d/dd（日）、m/mm（月）、M/MM（月份名）、yy/yyyy（年），可参考 formatDate 的实现。内置语言包正是利用这一点，让标题也能本地化，例如中文的"yyyy年mm月"会渲染出 "2015年04月"。

  渲染时的语言查询路径

  语言包在渲染环节被多处引用，理解了这些引用点有助于排查本地化失效问题：

  • 表头星期行：fillDow使用dates[this.o.language].daysMin生成<th>单元格（js/bootstrap-datepicker.js）；
  • 月份选择视图：fillMonths使用monthsShort渲染 12 个月份（js/bootstrap-datepicker.js）；
  • 主日历面板：fill从当前语言取today、clear、titleFormat，并渲染视图切换标题（js/bootstrap-datepicker.js）；
  • 输入值格式化：formatDate依据dates[language]中的DD/D/MM/M输出本地化文本（js/bootstrap-datepicker.js）；
  • 用户输入解析：parseDate同样按当前语言解析月份名（如 "一月"），支持本地化输入（js/bootstrap-datepicker.js）。

  只要语言包键存在且language选项指向正确代码，以上渲染点会自动切换到对应语言；若语言代码完全未知，则整体回退到英语。

  从右到左（RTL）语言支持

  阿拉伯语、希伯来语等 RTL 语言，可在语言包中加入rtl: true，日历将按从右到左的方向呈现，这是官方文档明确支持的能力。由于rtl属于locale_opts（js/bootstrap-datepicker.js），它也会随语言包自动生效。

  该开关在渲染层面由初始化逻辑处理：当this.o.rtl为真时，picker 根元素会追加datepicker-rtlCSS 类（js/bootstrap-datepicker.js），CSS 样式随后据此调整布局方向。默认rtl: false（见 defaults），即绝大多数非 RTL 语言保持从左到右。

  字符乱码问题与 UTF-8 编码

  官方文档特别提醒：如果浏览器（或你的用户）显示的字符乱码，很可能是浏览器以非 Unicode 编码加载了 JS 文件。解决办法是在script标签上显式声明charset="UTF-8"：

  <script src="bootstrap-datepicker.XX.js" charset="UTF-8"></script>

  其中XX为你的语言代码（如zh-CN）。这在中文、日文、俄文、阿拉伯文等非拉丁字符语言场景下尤为关键，是生产环境最常见的本地化故障来源之一，建议在部署时一并检查服务器返回的 HTTPContent-Type头是否包含charset=utf-8。

  完整示例与实战要点

  结合上述全部内容，一个支持中英文切换的完整初始化示例：

  <script src="jquery.js"></script> <script src="bootstrap-datepicker.js"></script> <script src="js/locales/bootstrap-datepicker.zh-CN.js" charset="UTF-8"></script> <script> $('.datepicker').datepicker({ language: 'zh-CN' // 指定语言；语言包缺失的字段自动回退到 'en' }); </script>

  实践中的关键结论：

  1. 引入顺序：语言包必须在插件主文件之后引入，且必须在.datepicker()调用之前完成注册；
  2. 代码格式：建议使用带地区后缀的 IETF 代码（如pt-BR、zh-CN），插件会自动执行de-DE → de → en三级回退；
  3. 联动选项：语言包中的format、rtl、weekStart会被自动合并为插件选项，无需重复配置；但通过 data 属性或 JS 参数显式传入的值优先级更高；
  4. 编码检查：出现乱码优先排查charset="UTF-8"，而非怀疑翻译文本本身；
  5. 扩展新语言：参照 js/locales/ 中任一现有文件的键结构，在.datepicker()前注册到$.fn.datepicker.dates即可。

  参考与深入阅读

  • 官方 i18n 文档：docs/i18n.rst
  • 语言选项完整定义：docs/options.rst（language）、docs/options.rst（weekStart）
  • 插件核心源码：js/bootstrap-datepicker.js
  • 内置语言包目录：js/locales/
  • 本地化行为测试：tests/suites/options.js

  【免费下载链接】bootstrap-datepickerA datepicker for twitter bootstrap (@twbs)项目地址: https://gitcode.com/gh_mirrors/bo/bootstrap-datepicker