feat: add language detector middleware and helpers #3787

lord007tn · 2024-12-31T06:22:59Z

Description

Add language detector middleware to support future i18n functionality in Hono applications.

Features

Detect language from multiple sources:
- Query parameters
- Cookies
- Accept-Language header
- URL path
Type-safe language access via c.get('language')
Configurable detection order
Support for language caching
Comprehensive test coverage

Usage

import { languageDetector } from 'hono/language'

app.use('*', languageDetector({
  supportedLanguages: ['en', 'ar', 'es'],
  fallbackLanguage: 'en'
}))

app.get('/', (c) => {
  const lang = c.get('language')
  return c.text(`Current language: ${lang}`)
})

### The author should do the following, if applicable

- [X] Add tests
- [X] Run tests
- [X] `bun run format:fix && bun run lint:fix` to format the code
- [X] Add [TSDoc](https://tsdoc.org/)/[JSDoc](https://jsdoc.app/about-getting-started) to document the code
…function

…function

lord007tn · 2024-12-31T06:30:08Z

if this got accepted am willing to add docs in the official website to let people know how to use it

codecov · 2024-12-31T07:13:41Z

Codecov Report

Attention: Patch coverage is 85.48387% with 27 lines in your changes missing coverage. Please review.

Project coverage is 91.60%. Comparing base (1e62912) to head (bdf1a30).
Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/middleware/language/language.ts	85.40%	27 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3787      +/-   ##
==========================================
- Coverage   91.71%   91.60%   -0.12%     
==========================================
  Files         160      162       +2     
  Lines       10181    10367     +186     
  Branches     2896     2985      +89     
==========================================
+ Hits         9338     9497     +159     
- Misses        842      869      +27     
  Partials        1        1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

lord007tn · 2024-12-31T10:17:38Z

i forgot to mention the full use of the middleware options are:

app.use(
  '*',
  languageDetector({
    // Detection strategies and their order
    order: ['path', 'querystring', 'cookie', 'header'],

    // Supported languages and fallback
    supportedLanguages: ['en', 'ar'],
    fallbackLanguage: 'en',

    // Query parameter settings
    lookupQuerystring: 'lang', // ?lang=en

    // Path settings
    lookupFromPathIndex: 0, // /en/about -> takes 'en'

    // Cookie settings
    lookupCookie: 'user-language',
    caches: false, // Set to false to disable caching

    // Header settings
    lookupFromHeaderKey: 'accept-language',

    // Language code handling
    ignoreCase: true,
    convertDetectedLanguage: (lang: string) => {
      // Optional: Convert language codes
      // e.g., 'en-US' -> 'en'
      return lang?.split('-')[0]?.toLowerCase() ?? '';
    },

    // Debugging
    debug: process.env.NODE_ENV !== 'production',
  }),
);

askorupskyy

I love it! This entirely solves the lang detection for me. Would also be cool to have a way to disable cookie/query detection altogether, or could this be done with order param?

askorupskyy · 2025-01-07T03:51:32Z

src/middleware/language/language.ts

+
+const DEFAULT_OPTIONS: DetectorOptions = {
+  order: ['querystring', 'cookie', 'header'],
+  lookupQuerystring: 'lang',


Suggested change

lookupQuerystring: 'lang',

lookupQueryString: 'lang',

I love it! This entirely solves the lang detection for me. Would also be cool to have a way to disable cookie/query detection altogether, or could this be done with order param?

yep just provide the order: ['header'] and it will only detect the header

@lord007tn

Can you apply the suggestion by @askorupskyy?

yusukebe · 2025-01-08T10:55:09Z

Thanks @lord007tn I'll review this later.

Hey @sor4chi What do you think of this feature?

sor4chi

Thank you for the wonderful PR, I liked it. I have one suggestion, what do you think?

Also, I feel a bit of discomfort with the naming hono/language. Personally, I would prefer something like hono/language-detector, but I’ll leave it to @yusukebe.

sor4chi · 2025-01-08T14:16:32Z

src/middleware/language/language.ts

+ * @param header Accept-Language header string
+ * @returns Array of parsed languages with quality scores
+ */
+export function parseAcceptLanguage(header: string): Array<{ lang: string; q: number }> {


I feel that this function overlaps in functionality with parseAccept. As an experiment, when I tried the following:

export function parseAcceptLanguage(header: string): Array<{ lang: string; q: number }> { return parseAccept(header) .map(({ type, q }) => ({ lang: type, q })) .sort((a, b) => b.q - a.q) }

I was able to pass the tests (though I may have overlooked edge cases). In this case, how about implementing a common parser in the utils and having both helper/accept and middleware/language reference it?

I also think the below @sor4chi 's idea is good.

how about implementing a common parser in the utils and having both helper/accept and middleware/language reference it?

@lord007tn What do you think of this?

yusukebe · 2025-01-19T09:27:30Z

Hi @lord007tn

Sorry for my super late response! Let's prepare to ship this middleware in the next minor version, v4.7.

@sor4chi

I also have concerns regarding the name and whether it should be hono/language-detector or hono/language. I know language is too general, but if the function imported from hono/language is languageDetector, the user can imagine the feature, so I think hono/language is ok. This means, as @lord007tn wrote above:

import { languageDetector } from 'hono/language'

yusukebe · 2025-01-19T09:37:57Z

@lord007tn

Can you apply the following diff to unify the coding style (using const for the function) with other code?

diff --git a/src/middleware/language/language.ts b/src/middleware/language/language.ts
index c298d3e9..e21f5a07 100644
--- a/src/middleware/language/language.ts
+++ b/src/middleware/language/language.ts
@@ -70,7 +70,7 @@ const DEFAULT_OPTIONS: DetectorOptions = {
  * @param header Accept-Language header string
  * @returns Array of parsed languages with quality scores
  */
-export function parseAcceptLanguage(header: string): Array<{ lang: string; q: number }> {
+export const parseAcceptLanguage = (header: string): Array<{ lang: string; q: number }> => {
   try {
     return header
       .split(',')
@@ -97,10 +97,10 @@ export function parseAcceptLanguage(header: string): Array<{ lang: string; q: nu
  * @param options Detector options
  * @returns Normalized language code or undefined
  */
-export function normalizeLanguage(
+export const normalizeLanguage = (
   lang: string | null | undefined,
   options: DetectorOptions
-): string | undefined {
+): string | undefined => {
   if (!lang) {
     return undefined
   }
@@ -126,7 +126,7 @@ export function normalizeLanguage(
 /**
  * Detects language from query parameter
  */
-export function detectFromQuery(c: Context, options: DetectorOptions): string | undefined {
+export const detectFromQuery = (c: Context, options: DetectorOptions): string | undefined => {
   try {
     const query = c.req.query(options.lookupQuerystring)
     return normalizeLanguage(query, options)
@@ -138,7 +138,7 @@ export function detectFromQuery(c: Context, options: DetectorOptions): string |
 /**
  * Detects language from cookie
  */
-export function detectFromCookie(c: Context, options: DetectorOptions): string | undefined {
+export const detectFromCookie = (c: Context, options: DetectorOptions): string | undefined => {
   try {
     const cookie = getCookie(c, options.lookupCookie)
     return normalizeLanguage(cookie, options)
@@ -238,7 +238,7 @@ function cacheLanguage(c: Context, language: string, options: DetectorOptions):
 /**
  * Detect language from request
  */
-function detectLanguage(c: Context, options: DetectorOptions): string {
+const detectLanguage = (c: Context, options: DetectorOptions): string => {
   let detectedLang: string | undefined

   for (const detectorName of options.order) {
@@ -277,7 +277,7 @@ function detectLanguage(c: Context, options: DetectorOptions): string {
  * @param userOptions Configuration options for the language detector
  * @returns Hono middleware function
  */
-export function languageDetector(userOptions: Partial<DetectorOptions> = {}): MiddlewareHandler {
+export const languageDetector = (userOptions: Partial<DetectorOptions>): MiddlewareHandler => {
   const options: DetectorOptions = {
     ...DEFAULT_OPTIONS,
     ...userOptions,
@@ -289,7 +289,7 @@ export function languageDetector(userOptions: Partial<DetectorOptions> = {}): Mi

   validateOptions(options)

-  return async function languageDetectorMiddleware(c, next) {
+  return async function languageDetector(c, next) {
     try {
       const lang = detectLanguage(c, options)
       c.set('language', lang)

lord007tn added 3 commits December 31, 2024 07:11

feat(language-detector): add language detector middleware and helper …

fcaa8c2

…function

chore(language-detector): add export in package.json

629eb03

chore(language-detector): add export to jsr

bdf1a30

yusukebe mentioned this pull request Dec 31, 2024

Language Detector Middleware for Hono #3785

Open

askorupskyy reviewed Jan 7, 2025

View reviewed changes

sor4chi reviewed Jan 8, 2025

View reviewed changes

yusukebe changed the title ~~add language detector middleware and helpers~~ feat: add language detector middleware and helpers Jan 9, 2025

yusukebe added the v4.7 label Jan 9, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add language detector middleware and helpers #3787

feat: add language detector middleware and helpers #3787

lord007tn commented Dec 31, 2024

lord007tn commented Dec 31, 2024

codecov bot commented Dec 31, 2024 •

edited

Loading

lord007tn commented Dec 31, 2024

askorupskyy left a comment •

edited

Loading

askorupskyy Jan 7, 2025

lord007tn Jan 7, 2025

yusukebe Jan 19, 2025

yusukebe commented Jan 8, 2025

sor4chi left a comment

sor4chi Jan 8, 2025

yusukebe Jan 19, 2025

yusukebe commented Jan 19, 2025

yusukebe commented Jan 19, 2025

feat: add language detector middleware and helpers #3787

Are you sure you want to change the base?

feat: add language detector middleware and helpers #3787

Conversation

lord007tn commented Dec 31, 2024

Description

Features

Usage

lord007tn commented Dec 31, 2024

codecov bot commented Dec 31, 2024 • edited Loading

Codecov Report

lord007tn commented Dec 31, 2024

askorupskyy left a comment • edited Loading

Choose a reason for hiding this comment

askorupskyy Jan 7, 2025

Choose a reason for hiding this comment

lord007tn Jan 7, 2025

Choose a reason for hiding this comment

yusukebe Jan 19, 2025

Choose a reason for hiding this comment

yusukebe commented Jan 8, 2025

sor4chi left a comment

Choose a reason for hiding this comment

sor4chi Jan 8, 2025

Choose a reason for hiding this comment

yusukebe Jan 19, 2025

Choose a reason for hiding this comment

yusukebe commented Jan 19, 2025

yusukebe commented Jan 19, 2025

codecov bot commented Dec 31, 2024 •

edited

Loading

askorupskyy left a comment •

edited

Loading