Language Detection Extension - DevLog

huseyinfiliz

Automatically Switch Languages Based on IP — Devlog

A few days ago, I started working on an idea that came up in the Flarum community: automatically switching a visitor’s language based on their IP address and browser language.

#39699 @Charity @Karl @Silvestrus @devnull @Tutrix @Wlork

I’m finally at the point where I can show you what I’ve built.

And honestly, I think the result turned out much better than I initially expected.

What does it do?

The extension automatically determines a visitor’s preferred Flarum locale using two sources:

Browser language preferences
IP-based country detection

The IP detection is handled entirely by the extension itself. There is no third-party API request to an external IP geolocation service.

It supports both IPv4 and IPv6, with the IP-to-country resolution performed locally using optimized IP range data and binary search.

That means there is no external API latency on the critical request path, and the visitor's IP does not need to be sent to a third-party geolocation service just to determine their country.

Based on the detected country and browser language, the extension can automatically select the appropriate language for the visitor.

Native integration with Flarum's localization flow

This is probably the part I’m most excited about.

I didn't want language detection to feel like a post-boot hack, a client-side language switch, or an after-the-fact redirect. I wanted it to become part of Flarum's existing localization flow.

The extension does this by placing a lightweight HTTP middleware directly before Flarum's core SetLocale middleware using insertBefore(SetLocale::class, ...).

This allows the visitor's preferred locale to be resolved before Flarum's core SetLocale middleware finalizes the locale for the request.

So instead of:

Flarum selects the fallback locale → extension tries to change it afterwards

the flow becomes:

Visitor request → extension detects the preferred locale → Flarum's SetLocale receives the detected locale → Flarum continues with that locale

The important part is that the extension isn't trying to replace Flarum's localization system.

It works with it.

The detected locale becomes the actual request locale that Flarum natively serves, rather than something that has to be corrected later on the frontend.

And because the detection is performed locally by the extension, there is no additional third-party API request blocking the request.

That was one of the main architectural goals of the project.

Visitor and country statistics

The extension can also collect statistics about the countries and IP addresses of visitors.

This gives administrators a much clearer picture of where their community is actually coming from.

You can see which countries are visiting your forum and use that information to make better decisions about language support.

The tracking is configurable, so administrators can decide whether they want to collect these statistics.

Missing languages

One of the other things I wanted to solve was the problem of discovering languages that your community might need without having to guess.

The extension can keep track of visitors requesting languages that aren't currently installed on your Flarum forum.

This means you can discover potential language needs from actual visitor traffic rather than simply relying on assumptions.

Settings

The settings page brings the main configuration options together, including language detection behavior, country/language mappings, fallback handling, and statistics.

The goal was to make the extension flexible enough for more advanced installations while keeping the basic setup straightforward.

How I built it

Now for the slightly unusual part of this story.

I'll be completely honest: I don't think I could have written this extension without my existing Flarum knowledge.

This was actually the first Flarum extension I developed using Claude CLI as a major part of the development process.

Before starting, I designed the architecture and prepared roughly 1,500 lines of instructions and technical context for the initial prompt.

Then I let Claude Sonnet 5 High work through the implementation.

The development process took roughly five days, around 30 hours of work, and cost approximately $500 in API usage.

And no, this wasn't a case of:

“Give Claude a prompt and come back five days later.”

It made plenty of mistakes.

A lot of them.

I had to continuously inspect the implementation, identify incorrect assumptions, investigate failures, and manually guide it toward the correct architecture. That added roughly another 10 hours of hands-on debugging and intervention.

Interestingly, the hardest part wasn't always fixing the bugs.

Diagnosing why they existed was often much harder.

Understanding Flarum's middleware pipeline, figuring out exactly when the locale becomes part of the request, and finding the correct place to integrate with the native SetLocale flow was a particularly interesting challenge.

Working directly with Flarum's localization catalogue and middleware pipeline at this level was also a first for me.

And honestly, I had a lot of fun doing it.

The result

What started as an idea from the Flarum discussion turned into something considerably more ambitious than I originally expected.

The extension currently provides:

Browser language detection
Local IP-based country detection
IPv4 support
IPv6 support
Automatic locale selection
Country-to-language mapping
Visitor country/IP statistics
Missing language statistics
Native integration with Flarum's SetLocale middleware
No third-party IP geolocation API required
Configurable detection and fallback behavior
A dedicated overview dashboard
Language management and statistics
Country statistics
Missing language tracking
A comprehensive settings page

I'm genuinely very happy with how this turned out.

I started this project because I wanted automatic language detection to feel like a native part of Flarum, rather than an extension bolted onto the side of it.

I think I got surprisingly close to that goal.

The extension isn't publicly released yet, but if you want to be one of the first people to try it, you can follow me here on Flarum or on GitHub. I'll share the release as soon as it's ready.

And, as always, I'd love to hear what you think.

What do you think about the architecture and the approach?

Especially if you have experience with Flarum's localization or middleware system, I'd be very interested in hearing your thoughts.

Tutrix

huseyinfiliz
This work is truly impressive. @Charity will surely be thrilled with this result.

huseyinfiliz

I need your help with testing! 🧪

I've currently installed all Flarum language packs on my test site so I can test the automatic language detection.

Please visit:

https://flarum.huseyinfiliz.com

Then let me know whether the forum automatically opens in your browser's preferred language.

The more people who test it with different browser languages, the more useful the results will be for me. So if you have a few seconds, please give it a try and let me know what language you get. 🙏

Thank you for helping me test this!

Tutrix

huseyinfiliz
When the page loads, German is selected, so that part works.
But the manual language selection (dropdown) won't scroll.
Not everything is in German either; see the tags and footer. The logos in the footer aren't loading either.

Capybara

huseyinfiliz Checked — displays correctly in my language

Capybara

Tutrix But the manual language selection (dropdown) won't scroll.

I think this is an edge case — it's unlikely anyone would install more than 5-6 languages for themselves 👀

Capybara

Tutrix Not everything is in German either; ee the tags and footer

Because they're set manually and don't have translation strings. Everything that has keys on Weblate is translated

Tutrix

Capybara
For example, if I manually select “English,” I can't switch back to German because it's no longer selectable without scrolling.

huseyinfiliz

Capybara Tutrix This shows that the extension is working correctly. Thank you for testing it.

The language selector dropdown belongs to Flarum, and in a normal forum, you would not usually have this many language extensions installed anyway.

Also, this extension only automatically selects the language on the visitor’s first visit to the forum, based on their IP address or their system/browser language.

As for the image not loading in the footer, that happened because the homepage of flarum.org was changed.

ClaudiusH

huseyinfiliz Tried with German and Persian (after deleting cookies & local storage) and initial redirect worked as designed. Loading time was quite long though before any elements of the page got painted, but that might just be your test setup and not due to the extension.
Well done! I was worried it would override user preference from the language selector, but that prefence sticks after reloads on the same browser.

huseyinfiliz

ClaudiusH What makes this possible is that I didn’t use any JavaScript on the forum side in the first place. In other words, this extension does not handle language selection with JavaScript. Instead, it integrates into Flarum’s built-in language management by adding a middleware layer.

It also stores the language selection in its own cookie, ensuring that each user only goes through the automatic language detection process once. After that, the user can switch to any language they want, and the extension does not interfere with their choice again.

The reason my test forum loads slowly is that it is running with 100+ extensions, some of which have not been optimized yet, while the server only has 256 MB of RAM. The forum also has 100,000 members. I need this setup in order to test the performance of my extensions under extreme conditions.

thatsgolden

huseyinfiliz

I tried a chinese environment, it doesn't work, maybe the Accept-Language "zh-CN" doesn't match the "zh-Hans" language package?

zh-CN, zh-SG → zh-Hans
zh-TW, zh-HK, etc. Should all be  zh-Hant

huseyinfiliz

thatsgolden Yes, no matching language pack was found for "zh-cn". Thank you for the feedback; I’ll fix this.

huseyinfiliz

thatsgolden

Smarter fallback for split-script languages (zh, sr, no, ku)

TL;DR: If you have both variants of a split language installed (e.g. Simplified + Traditional Chinese), a visitor whose browser just says zh now gets routed to the more common variant instead of falling back to your forum's default language.

The problem

language-detection matches a visitor's browser locale against your installed language packs using a tiered lookup (exact match → progressive truncation → sibling match), following RFC 4647-style "lookup" behavior.

A handful of languages are published as multiple, separate packs rather than one:

Chinese → zh-Hans (Simplified) / zh-Hant (Traditional)
Serbian → sr-Cyrl (Cyrillic) / sr-Latn (Latin)
Norwegian → nb (Bokmål) / nn (Nynorsk)
Kurdish → ckb (Sorani) / kmr (Kurmanji)

Browsers, meanwhile, often just send the bare macrolanguage code — zh, sr, no, ku — with no hint of which variant the visitor actually wants.

Previously, if only one of a pair was installed, the matcher correctly resolved to it. But if both were installed, the request was genuinely ambiguous, so it was declined — and the visitor fell all the way through to your forum's default_locale, even if that had nothing to do with the language they asked for. A zh visitor on a forum with both Chinese packs installed and English as default would land on English, not Chinese.

The fix

For these four macrolanguages specifically, ambiguity now resolves to the more widely-spoken variant instead of being declined:

Requested	Resolves to (when both installed)	Why
`zh`	`zh-Hans` (Simplified)	Used by far more readers (mainland China, Singapore); the two scripts are close enough that a "wrong" guess is still largely readable.
`sr`	`sr-Latn` (Latin)	Dominates everyday digital/online use, even though Cyrillic is the official script.
`no`	`nb` (Bokmål)	Used by roughly 85–90% of Norwegians.
`ku`	`kmr` (Kurmanji)	Spoken by roughly 65% of Kurds vs. ₂₀% for Sorani.

Everything else about the matching logic is unchanged: exact matches, region-based hints (e.g. zh-CN → Simplified, zh-TW → Traditional — these were already resolved unambiguously via region and aren't affected by this change), and truncation all still take priority. This fallback only kicks in when the request is genuinely down to "which flavor of this language" with no other signal to go on.

If only one variant of a given language is installed, behavior is exactly as before — that single pack still wins by default, no ambiguity involved.

Why not treat all split languages this way?

We keep this exception scoped to these four rather than generalizing it. For truly distinct written standards — different alphabets or heavily diverged grammar/vocabulary — guessing wrong can hand a visitor text they genuinely can't read, which is worse than falling back to the site default. These four were judged to have variants close enough (or one clearly dominant enough) that a same-language guess beats a different-language fallback. Happy to hear arguments for expanding or adjusting the list.

huseyinfiliz

thatsgolden ClaudiusH Tutrix Capybara I’ve now updated the admin settings so that language detection is based on the visitor’s country, determined via their IP address, rather than their browser/system language. If possible, could you try it again and share the results with me? If you have some time, it would also be great if you could test it with a VPN.

By the way, when I make the code public, you’ll probably be quite surprised when you see how the extension detects the country from an IP address. I tested it in Python using nearly 1 million publicly available IPv4 and IPv6 addresses from the internet, and I was able to achieve close to a 90% regional match rate. I’m really curious to see how well it performs in real-world testing.

Capybara

huseyinfiliz I use VPN almost all the time — usually set to the Netherlands — and when I visit the site, it automatically switches to Dutch. If turn off the VPN add refresh the page, the forum stays in Dutch, so it's probably remembering/caching that

huseyinfiliz

Capybara Thank you for taking the time to test it. There are actually two reasons for this.

First, Flarum’s built-in locale system normally keeps the language unchanged unless the user manually switches it. My extension, on the other hand, only forces a language selection once for each individual user. For visitors, this happens once every 24 hours, while for registered members, it happens only once in their lifetime.

This is purely an architectural decision, and I believe it makes sense.

thatsgolden

huseyinfiliz It works perfectly for me. I tested it using VPN servers from various countries across multiple continents in InPrivate mode, and all detections succeeded.

huseyinfiliz

thatsgolden Thank you very much for taking the time. I’ll probably continue testing it for another two days and release the 1.x version on Monday. In the meantime, I’d be happy to hear any additional suggestions you may have.

Tutrix

huseyinfiliz I tested it briefly yesterday, too: When I visit the site, it's in German. If I visit it via a VPN using Spain, it's in Spanish. So it works.