在实作多国语言的 Web 服务时,会需要去读取客户端发送来的 HTTP 请求标头中的 Accept-Language 字段,来判断客户端偏好使用的语言。然而,Rocket 框架并未内置解析 Accept-Language 字段的功能,开发者只能自行去撰写程序来想办法用 Accept-Language 字段的原始数据去做客户端的语言判断,不但麻烦又很不安全。

一个 Accept-Language 字段的值可能如以下这样:

zh-TW,zh;q=0.7,en-US;q=0.6,en;q=0.5

以上的值,代表客户端想要优先使用台湾的繁体中文,如果没有的话就使用任意地区的中文,如果还是没有的话就使用美国的英文,如果又没有的话就使用任意地区的英文。

accept-language Request Guard for Rocket Framework

「accept-language Request Guard for Rocket Framework」是笔者开发出来的套件,将可以读取 Accept-Language 字段并且进行语言判断的功能写成请求守卫,一劳永逸。使用 accept-language 这个 crate 来进行 Accept-Language 字段值的解析,并转成 unic-langid 这个 crate 提供的 LanguageIdentifier 结构体的实体来保存。

Crates.io

Cargo.toml

rocket-accept-language = "*"

使用方法

在 Rocket 框架启动前,先创建出 LanguageIdentifier 结构实体的数组,用来表示这个 Rocket 应用程序支持的语言。接着再把这个 LanguageIdentifier 数组,注册成 Rocket 的应用程序状态。language_region_pairs 宏能以很小的开支(overhead)来创建 Vec<LanguageIdentifier> 结构实体。

在 Rocket 框架的路由处理程序中,借由放置 rocket_accept_language 这个 crate 所提供的 AcceptLanguage 请求守卫,来解析 HTTP 请求标头中的 Accept-Language 字段。AcceptLanguage 的结构实体提供了 get_appropriate_language_region 方法,可以传入一个 LanguageIdentifier 数组切片,根据 Rocket 应用程序有支持的语言来判断出最符合 HTTP 请求的语言。

get_appropriate_language_region 方法会回传 unic-langid 这个 crate 提供的 Language 和 Region 结构体的实体。透过 language 宏和 region 宏,可以用常数创建出 Language 和 Region 结构实体并保存起来,方便重用。

以下是一个使用范例:

#[macro_use]
extern crate rocket;

use rocket::State;
use rocket_accept_language::{
    language, language_region_pairs, region,
    unic_langid::subtags::{Language, Region},
    AcceptLanguage, LanguageIdentifier,
};

const LANGUAGE_ZH: Language = language!("zh");
const LANGUAGE_EN: Language = language!("en");
const LANGUAGE_JP: Language = language!("ja");
const REGION_CN: Region = region!("cn");
const REGION_TW: Region = region!("tw");

struct SupportLanguages {
    language_identifiers: Vec<LanguageIdentifier>,
}

impl SupportLanguages {
    fn as_language_identifiers(&self) -> &[LanguageIdentifier] {
        &self.language_identifiers
    }
}

#[get("/")]
fn hello(
    accept_language: &AcceptLanguage,
    support_languages: &State<SupportLanguages>,
) -> &'static str {
    let (language, region) = accept_language
        .get_appropriate_language_region(support_languages.as_language_identifiers())
        .unwrap_or((LANGUAGE_EN, None));

    match language {
        LANGUAGE_ZH => match region.unwrap_or(REGION_TW) {
            REGION_CN => "哈罗!",
            _ => "哈啰!",
        },
        LANGUAGE_JP => "ハロー",
        _ => "Hello!",
    }
}

#[launch]
fn rocket() -> _ {
    let support_languages = SupportLanguages {
        language_identifiers: language_region_pairs!["zh-TW", "zh_CN", "ja", "en"],
    };

    rocket::build().manage(support_languages).mount("/", routes![hello])
}