Support languages other than English

[dnywh]

Overkill for now but worth jotting down ideas about internationalisation (here!) for the future.

Supporting other languages is a great way to break into new areas, particularly those not in the global north that either speak English or can get by with it.

Resources

• https://vitonsky.net/blog/2025/05/17/language-detection/

[dnywh]

Martín (@Martinalmina31) has graciously volunteered to help out with Spanish translations, see #9 (comment). He agrees that there’s a big composting community in Latin America, potentially blocked by language support. This is a nice nudge to get this moving!

I did a ‘spike’ this morning to check the following:

• How much work will adding multiple language support be?
• Can we add translations incrementally over time without blocking other work?
• Can we do it in a way that doesn’t hinder other work or bloat the codebase?

The answers look promising. See below. The gist:

1. Let’s hardcode English as the locale in the i18n branch and then merge it to the main branch.
2. Any time we touch a a component, move its strings to en.json
3. Start a new branch later to address the below points and the Spanish strings. The latter could be done in one hit, at least via a crappy machine translation to improve upon.

How much work will adding multiple language support be?

My spike (published as the i18n branch) already works for basic string placement based on hardcoded locale. It's missing some key features that I’m not sure how long will take to add/fix:

• Take a locale like es-AR and ‘fall back’ to es.json (rather than looking for es-ar.json).
• Handle complex sentences with numbers, ternaries, etc. E.g. “You have three listings, one of which is hidden”. That mixes logic, formatting, and language.
• We need to think through how we want to translate newsletters and other static pages. I think the without i18n routing makes sense for most of Peels, but we might need to make an exception (e.g. /newsletter/issue-name/es, /privacy/es) for static pages to save huge and obscure translation paragraphs. This means mixing routing, which their examples include but who knows how difficult it is to implement.
• What about non-web surfaces like emails? How do we know what language to send an email to someone? Can we even do that with Supabase’s built-in auth email functionality? The alternative is blocked: Signing up sometimes fails #3. Do we need to save someone’s language preference to their profile upon sign-up and make assumptions based on their browser?

Overall though, not much to get to 90% translated. The immediate work is taking all the hardcoded strings and moving them to en.json, whilst just hardcoding that as the locale for everyone. We should do that now going forward, for everything to prepare us for other languages.

Can we add translations incrementally over time without blocking other work?

Yes, we can incrementally add Spanish (and other language) strings over time, with ‘unfilled’ strings falling back to English. We could also consider getting a leg-up via LLM translations (e.g. Claude having a first pass at taking en.json to es.json, de.json).

We should do what I wrote above: any new (general) work should have language put in en.json, not hardcoded in the component.

Side note: we can upgrade to CrowdIn in the future if we really need an interface for translators. We might squeeze in to the free plan, I’m not sure. I prefer not to do this, as it adds yet another ‘thing’ to manage, but I mention it now as I‘m likely to forget. I believe next-intl is made by the CrowdIn folks, so it should play nice.

Can we do it in a way that doesn’t hinder other work or bloat the codebase?

Yep, the next-intl approach seems quite lightweight. Though this will inevitably be more involved than hardcoded English strings. It will also make inspecting markup a little more vague. E.g going from:

<h1>Find a home for your food scraps, wherever you are</h1>
<p>Peels connects folks with food scraps to those who compost. It’s a free, non-commercial, community project.</p>

to:

<h1>{t('title')}</h1>
<p>{t('subtitle')}</p>

...obviously sacrifices some clarity. But the benefits are worth the cost: opening up Peels to a huge chunk of the world.

[Martinalmina31]

Great. Just let me know what needs to be done and I'll step in. I don't know much about coding but do know spanish 😅 Martín Almiña +61459322682

…

On Thu, Jun 12, 2025 at 12:29 PM Danny White ***@***.***> wrote: Martín ***@***.*** <https://github.com/Martinalmina31>) has graciously volunteered to help out with Spanish translations, see #9 (comment) <#9 (comment)>. He agrees that there’s a big composting community in Latin America, potentially blocked by language support. This is a nice nudge to get this moving! I did a ‘spike’ this morning to check the following: - How much work will adding multiple language support be? - Can we add translations incrementally over time without blocking other work? - Can we do it in a way that doesn’t hinder other work or bloat the codebase? The answers look promising. See below. The gist: 1. Let’s hardcode English as the locale in the i18n branch <https://github.com/dnywh/peels/tree/i18n>) and then merge it to the main branch. 2. Any time we touch a a component, move its strings to en.json 3. Start a new branch later to address the below points and the Spanish strings. The latter could be done in one hit, at least via a crappy machine translation to improve upon. How much work will adding multiple language support be? My spike (published as the i18n branch <https://github.com/dnywh/peels/tree/i18n>) already works for basic string placement based on hardcoded locale. It's missing some key features that I’m not sure how long will take to add/fix: - Take a locale like es-AR and ‘fall back’ to es.json (rather than looking for es-ar.json). - Handle complex sentences with numbers, ternaries, etc. E.g. “You have *three* listings, one of which is hidden”. That mixes logic, formatting, and language. - We need to think through how we want to translate newsletters and other static pages. I think the *without* i18n routing makes sense for most of Peels, but we might need to make an exception (e.g. /newsletter/issue-name/es, /privacy/es) for static pages to save huge and obscure translation paragraphs. This means *mixing routing*, which their examples include <https://github.com/amannn/next-intl/tree/main/examples/example-app-router-without-i18n-routing> but who knows how difficult it is to implement. Overall though, not much to get to 90% translated. The immediate work is taking all the hardcoded strings and moving them to en.json, whilst just hardcoding that as the locale for everyone. *We should do that now going forward, for everything* to prepare us for other languages. Can we add translations incrementally over time without blocking other work? Yes, we can incrementally add Spanish (and other language) strings over time, with ‘unfilled’ strings falling back <https://next-intl.dev/docs/usage/configuration#messages-fallback> to English. We could also consider getting a leg-up via LLM translations (e.g. Claude having a first pass at taking en.json to es.json, de.json). We should do what I wrote above: any new (general) work should have language put in en.json, not hardcoded in the component. Side note: we can upgrade to CrowdIn <https://crowdin.com/> in the future if we really need an interface for translators. We might squeeze in to the free plan, I’m not sure. I prefer not to do this, as it adds yet another ‘thing’ to manage, but I mention it now as I‘m likely to forget. I believe next-intl <https://next-intl.dev> is made by the CrowdIn folks, so it should play nice. Can we do it in a way that doesn’t hinder other work or bloat the codebase? Yep, the next-intl <https://next-intl.dev> approach seems quite lightweight. Though this will inevitably be more involved than hardcoded English strings. It will also make inspecting markup a little more vague. E.g going from: <h1>Find a home for your food scraps, wherever you are</h1><p>Peels connects folks with food scraps to those who compost. It’s a free, non-commercial, community project.</p> to: <h1>{t('title')}</h1><p>{t('subtitle')}</p> ...obviously sacrifices some clarity. But the benefits are worth the cost: opening up Peels to a huge chunk of the world. — Reply to this email directly, view it on GitHub <#5 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BRQEVVH4UT6HEPDD2JCFPI33DDQX5AVCNFSM6AAAAAB5P6CJLKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNBUGAZTINY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[dnywh]

Thanks @Martinalmina31. I’ll let you know when it’s ready.

I’ve just merged in that above spike via #14, so people with their browser set to Spanish should see most parts of the homepage in (rudimentary) Spanish.

I need to move all English text over to messages/en.json before we can start properly translating. I’ll reach out again when that’s done!

[dnywh]

Hey @Martinalmina31! Happy to say that I’ve just added Spanish (and other) language support in #55. You should now be able to go to https://www.peels.app/ and, if you’re in Argentina (or another Spanish-speaking country), automatically see it in Spanish.

Or you can change your language preference in the site footer (logged out) or profile preferences (logged in).

If you’re still interested in looking over the first-draft Spanish and fixing any bad translations, please don’t hesitate to drop them here or file an issue. Thanks so much.