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 87.81513% with 29 lines in your changes missing coverage. Please review.

Project coverage is 90.69%. Comparing base (1e62912) to head (ecdbd5e).
Report is 31 commits behind head on next.

Files with missing lines	Patch %	Lines
src/middleware/language/language.ts	84.02%	27 Missing ⚠️
src/helper/accepts/accepts.ts	0.00%	1 Missing ⚠️
src/utils/accept.ts	98.50%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #3787      +/-   ##
==========================================
- Coverage   91.71%   90.69%   -1.03%     
==========================================
  Files         160      165       +5     
  Lines       10181    10480     +299     
  Branches     2896     3086     +190     
==========================================
+ Hits         9338     9505     +167     
- Misses        842      974     +132     
  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.

src/middleware/language/language.ts

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 · 2025-01-23T21:19:44Z

i just pushed new parse-accept helpers
and unified the logic in accept and language

my question now is for v4.7 we merge this and then turn to the docs or I do the docs to get this merged?

sor4chi · 2025-01-23T23:32:35Z

If you submit a PR to the honojs/website and include a link to this PR, @yusukebe should merge it at the same time as the release.

sor4chi

Very good! Thank you for your support.
I have noted a few other points of concern.

src/middleware/language/index.ts

src/utils/parse-accept.ts

sor4chi · 2025-01-23T23:37:42Z

src/utils/parse-accept.ts

+  if (qVal === undefined) {
+    return 1.0
+  }
+  if (qVal === '') {
+    return 1
+  }
+  if (qVal === 'NaN') {
+    return 0
+  }


q: is there any reason for using "1.0" and "0"?

sor4chi · 2025-01-23T23:42:54Z

src/middleware/language/language.ts

+  language: string
+}
+
+const DEFAULT_OPTIONS: DetectorOptions = {


It would be better to export this.

lord007tn · 2025-01-25T21:21:51Z

Very good! Thank you for your support. I have noted a few other points of concern.

i fixed some points you raised.

sor4chi

Looks good, thank you very much!

lord007tn · 2025-01-26T17:25:35Z

If you submit a PR to the honojs/website and include a link to this PR, @yusukebe should merge it at the same time as the release.

I’ve added the documentation honojs/website#569 to the honojs website. Since I’m not a technical writer by trade, please feel free to suggest improvements or refine the content for clarity and accuracy.

src/middleware/language/language.ts

src/utils/parse-accept.ts

src/utils/parse-accept.test.ts

src/middleware/language/index.ts

yusukebe · 2025-02-03T10:14:20Z

Hi @lord007tn

Almost all are good. I've left comments. Check them!

src/middleware/language/index.ts

yusukebe · 2025-02-06T13:10:30Z

Hi @lord007tn

Looks good to me! I'll merge this into the next branch for the next minor version and ship the v4.7 soon! Thank you for the great work!

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

Loading
Loading status checks…

bdf1a30

yusukebe mentioned this pull request Dec 31, 2024

Language Detector Middleware for Hono #3785

Closed

askorupskyy reviewed Jan 7, 2025

View reviewed changes

sor4chi reviewed Jan 8, 2025

View reviewed changes

src/middleware/language/language.ts Show resolved Hide resolved

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

lord007tn added 2 commits January 23, 2025 21:58

feat: new parse-accept helper, add edge case tests

05007db

chore: add jsr for parse-accept

Loading
Loading status checks…

44fe77d

sor4chi reviewed Jan 23, 2025

View reviewed changes

fix: export default options, remove empty type

Loading
Loading status checks…

6b4e053

sor4chi approved these changes Jan 25, 2025

View reviewed changes

lord007tn mentioned this pull request Jan 26, 2025

docs: add language middleware documentation honojs/website#569

Merged

yusukebe reviewed Jan 27, 2025

View reviewed changes

src/middleware/language/language.ts Outdated Show resolved Hide resolved

lord007tn added 2 commits January 27, 2025 20:53

refac: rename languageDetectorMiddleware to languageDetector

Loading
Loading status checks…

e84b840

chore format code

Loading
Loading status checks…

2127d80

yusukebe reviewed Feb 3, 2025

View reviewed changes

src/utils/parse-accept.ts Outdated Show resolved Hide resolved

src/utils/parse-accept.test.ts Outdated Show resolved Hide resolved

yusukebe reviewed Feb 3, 2025

View reviewed changes

src/middleware/language/index.ts Outdated Show resolved Hide resolved

refac: apply patches

Loading
Loading status checks…

007ea3d

yusukebe requested changes Feb 4, 2025

View reviewed changes

src/middleware/language/index.ts Outdated Show resolved Hide resolved

refactor: change export type in language

Loading
Loading status checks…

ecdbd5e

yusukebe changed the base branch from main to next February 6, 2025 13:08

yusukebe approved these changes Feb 6, 2025

View reviewed changes

yusukebe merged commit fa92596 into honojs:next Feb 6, 2025
16 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GitHub Sponsors

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

yusukebe commented Jan 19, 2025

yusukebe commented Jan 19, 2025

lord007tn commented Jan 23, 2025

sor4chi commented Jan 23, 2025

sor4chi left a comment

sor4chi Jan 23, 2025

sor4chi Jan 23, 2025

lord007tn commented Jan 25, 2025

sor4chi left a comment

lord007tn commented Jan 26, 2025

yusukebe commented Feb 3, 2025

yusukebe commented Feb 6, 2025

feat: add language detector middleware and helpers #3787

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

yusukebe commented Jan 19, 2025

yusukebe commented Jan 19, 2025

lord007tn commented Jan 23, 2025

sor4chi commented Jan 23, 2025

sor4chi left a comment

Choose a reason for hiding this comment

sor4chi Jan 23, 2025

Choose a reason for hiding this comment

sor4chi Jan 23, 2025

Choose a reason for hiding this comment

lord007tn commented Jan 25, 2025

sor4chi left a comment

Choose a reason for hiding this comment

lord007tn commented Jan 26, 2025

yusukebe commented Feb 3, 2025

yusukebe commented Feb 6, 2025

codecov bot commented Dec 31, 2024 •

edited

Loading

askorupskyy left a comment •

edited

Loading