From 6c1bf76aab349c34f2196df78b8bd612e816a92b Mon Sep 17 00:00:00 2001 From: Adam Masiarek Date: Mon, 17 Aug 2026 06:29:36 -0400 Subject: [PATCH 1/3] docs: explain how to use BetterVoting in another language BetterVoting ships four languages and there is no way to discover that from the interface -- i18n.ts uses the browser language detector, and nothing in packages/frontend/src offers a language switcher. The only way to choose one is the ?lng= URL parameter, which is documented for translators in the contribution guide and nowhere a voter would ever look. Covers: that detection is automatic and most people need nothing; the codes for the four current languages; how to append the parameter to a link that already has a query string; and how to help add a language. Three things the page is careful about, all of which have caught people out: - The choice is CACHED. i18next-browser-languagedetector's default order writes the selection to localStorage and a cookie, so it persists after the parameter is gone -- and returning to English needs an explicit ?lng=en rather than just dropping the parameter. This gets its own warning callout; it is the single most confusing behaviour here. - Mixed English is CORRECT, not broken. Only Priority 0 is translated and fallbackLng is 'en', so a page can legitimately be part translated. Saying so prevents a voter reporting it as a fault. - The election's own content is never translated. Candidate names, race titles, descriptions and the organiser's emails are whatever they wrote. A Spanish interface can carry an English ballot question, and that is the system working correctly. The admin section draws the practical conclusion: sending ?lng= links is worth doing for a known-language group, but it translates the buttons around your text and not the text itself, so a genuinely bilingual electorate is better served by writing the race description in both languages. Lists only the four languages currently on main. German is in review (#1560) and can be added in a one-line follow-up once it merges. Co-Authored-By: Claude Opus 5 --- docs/help/using_another_language.md | 70 +++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/help/using_another_language.md diff --git a/docs/help/using_another_language.md b/docs/help/using_another_language.md new file mode 100644 index 000000000..e2a1eec01 --- /dev/null +++ b/docs/help/using_another_language.md @@ -0,0 +1,70 @@ +--- +layout: default +title: Using BetterVoting in Another Language +nav_order: 21 +parent: BetterVoting Documentation +--- + +# Using BetterVoting in Another Language + +BetterVoting is available in several languages. This page explains how to choose one, what to expect, and what to do if you'd like to help add your own. + +## It usually happens by itself + +**BetterVoting reads the language setting from your browser and matches it if it can.** If your device is set to Spanish and Spanish is available, you'll see Spanish without doing anything. + +So most people never need this page. If the site is already showing your language, nothing here applies to you. + +## Choosing a language yourself + +There is no language menu on the site. To pick a language, **add `?lng=` and the language code to the end of the address**: + +``` +https://bettervoting.com/your-election-id?lng=es +``` + +| Language | Code | Add to the address | +|:---|:---|:---| +| English | `en` | `?lng=en` | +| Spanish · Español | `es` | `?lng=es` | +| Polish · Polski | `pl` | `?lng=pl` | +| Portuguese (Brazil) · Português | `pt-BR` | `?lng=pt-BR` | + +More languages are added over time, so this list may be shorter than what's actually available — it costs nothing to try your own code and see. + +{: .warning } +> **Your choice is remembered.** Once you've used `?lng=`, BetterVoting keeps showing you that language on later visits, even without the parameter. To switch back to English you have to say so explicitly, with `?lng=en` — clearing the parameter alone won't do it. This surprises people who were only trying a language out. + +If your election link already has a `?` in it, join the language setting on with `&` instead: + +``` +https://bettervoting.com/your-election-id?something=1&lng=es +``` + +## Why some text is still in English + +**This is expected, and it doesn't mean anything is broken.** + +Translations cover the parts voters actually use — the ballot, the instructions for your voting method, the confirmation screen, and the main results. Administration screens and less-used pages are still English for most languages. + +Anything not yet translated falls back to English rather than showing blank or breaking, so a page may legitimately be a mix of the two. Your ballot will be in your language; the deeper settings screens may not be. + +**The election's own content is never translated.** Candidate names, race titles, the description written by whoever set the election up, and any message they emailed you all appear exactly as they wrote them. BetterVoting translates its own interface, not your organiser's words — so a Spanish interface can carry an English ballot question, and that's correct behaviour rather than a gap. + +## If your language isn't listed + +Two things worth knowing. + +**Nothing is lost by using English.** Every voting method works identically in every language; the interface language changes no part of how your ballot is counted. + +**You can add your language.** BetterVoting's translations are contributed by its users, and adding one needs no programming — it's a text file edited through the GitHub website. If you're comfortable in English and fluent in another language, you're qualified. See [Adding Translations](../contributions/writers/3_adding_translations.md) for the process. + +Translators aren't expected to work alone or to be professional linguists. Every translation gets proof-read, and at least one proof-reader is a native speaker, so you're checked rather than trusted blindly. Helping proof-read an existing language is just as useful as starting a new one — and quite a bit quicker. + +## For election administrators + +**You can send voters a link that opens in their language.** Just append `?lng=` and the code to the voting link you share. That's worth doing for a group you know reads a particular language, since it removes any dependence on how their device happens to be configured. + +Be aware of the two limits above when you do: the choice sticks in that person's browser afterwards, and **your own text stays in whatever language you wrote it in.** If you want your voters to read the ballot question in Spanish, you have to write it in Spanish — setting `?lng=es` translates the buttons around it, not your words. + +For a mixed-language electorate, writing the important text in both languages inside the race description is more reliable than expecting the interface language to carry the meaning. From d8aef2e413560faf9618aae15a2406d7a0a65090 Mon Sep 17 00:00:00 2001 From: Adam Masiarek Date: Mon, 17 Aug 2026 06:43:49 -0400 Subject: [PATCH 2/3] docs: list German, French and Italian on the language page Adds the three languages currently in review to the table, marked so the page stays truthful either way: a voter who tries ?lng=de before it merges learns that from the page rather than from a screen that stubbornly stays English. The marker is prose rather than a PR number, so the only edit needed when they land is deleting three words -- no link to rot, and nothing that reads oddly to a user who has no idea what a pull request is. Also splits the closing line in two. It was doing two jobs at once: telling readers the list may lag reality, and telling them to just try their code. The second is the actionable half and now stands on its own. Co-Authored-By: Claude Opus 5 --- docs/help/using_another_language.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/help/using_another_language.md b/docs/help/using_another_language.md index e2a1eec01..722444594 100644 --- a/docs/help/using_another_language.md +++ b/docs/help/using_another_language.md @@ -23,14 +23,19 @@ There is no language menu on the site. To pick a language, **add `?lng=` and the https://bettervoting.com/your-election-id?lng=es ``` -| Language | Code | Add to the address | -|:---|:---|:---| -| English | `en` | `?lng=en` | -| Spanish · Español | `es` | `?lng=es` | -| Polish · Polski | `pl` | `?lng=pl` | -| Portuguese (Brazil) · Português | `pt-BR` | `?lng=pt-BR` | - -More languages are added over time, so this list may be shorter than what's actually available — it costs nothing to try your own code and see. +| Language | Code | Add to the address | | +|:---|:---|:---|:---| +| English | `en` | `?lng=en` | | +| Spanish · Español | `es` | `?lng=es` | | +| Polish · Polski | `pl` | `?lng=pl` | | +| Portuguese (Brazil) · Português | `pt-BR` | `?lng=pt-BR` | | +| German · Deutsch | `de` | `?lng=de` | *in review* | +| French · Français | `fr` | `?lng=fr` | *in review* | +| Italian · Italiano | `it` | `?lng=it` | *in review* | + +Languages marked *in review* have been submitted and are being checked by a native speaker before going live — try the code and you'll see whether yours has landed yet. + +More languages are added over time, so this list may be shorter than what's actually available. It costs nothing to try your own code and see. {: .warning } > **Your choice is remembered.** Once you've used `?lng=`, BetterVoting keeps showing you that language on later visits, even without the parameter. To switch back to English you have to say so explicitly, with `?lng=en` — clearing the parameter alone won't do it. This surprises people who were only trying a language out. From a14031c5354e8c3d13cf48f5fb8e2c471e95d397 Mon Sep 17 00:00:00 2001 From: Adam Masiarek Date: Mon, 17 Aug 2026 06:48:39 -0400 Subject: [PATCH 3/3] docs: stop the language examples looking like working links The examples used https://bettervoting.com/your-election-id?lng=es in a fenced code block. A code block invites copying, and the URL is well formed, so the natural thing a reader does is paste it -- and gets '400: Election not found', because no election has that id. Confirmed by a reader doing exactly that. Two changes: - The instruction now leads with what the reader actually has to do -- take YOUR address and append the parameter -- instead of presenting a URL to imitate. The placeholder is a short opaque id (a1b2c3) that reads as a stand-in rather than a real path segment, and the page says outright that opening the examples as written will error. - The ?-vs-& case becomes a three-column table (your link, what to add, the result) rather than a second pasteable URL. That was the harder half to explain and the table carries it better than prose did. Neither example now sits alone in a code fence where it can be mistaken for something to run. Co-Authored-By: Claude Opus 5 --- docs/help/using_another_language.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/help/using_another_language.md b/docs/help/using_another_language.md index 722444594..df5bd7041 100644 --- a/docs/help/using_another_language.md +++ b/docs/help/using_another_language.md @@ -17,11 +17,11 @@ So most people never need this page. If the site is already showing your languag ## Choosing a language yourself -There is no language menu on the site. To pick a language, **add `?lng=` and the language code to the end of the address**: +There is no language menu on the site. To pick a language, **take the address you already have and add `?lng=` and the language code to the end of it**. -``` -https://bettervoting.com/your-election-id?lng=es -``` +So if your voting link is `bettervoting.com/a1b2c3`, you'd open `bettervoting.com/a1b2c3?lng=es` for Spanish. + +The examples below use `a1b2c3` to stand in for your own election's address — replace it with yours. Opening the examples as written will give you an "Election not found" error, because no such election exists. | Language | Code | Add to the address | | |:---|:---|:---|:---| @@ -40,11 +40,12 @@ More languages are added over time, so this list may be shorter than what's actu {: .warning } > **Your choice is remembered.** Once you've used `?lng=`, BetterVoting keeps showing you that language on later visits, even without the parameter. To switch back to English you have to say so explicitly, with `?lng=en` — clearing the parameter alone won't do it. This surprises people who were only trying a language out. -If your election link already has a `?` in it, join the language setting on with `&` instead: +If your link already contains a `?`, join the language setting on with `&` instead of a second `?`: -``` -https://bettervoting.com/your-election-id?something=1&lng=es -``` +| Your link | Add this | Result | +|:---|:---|:---| +| `bettervoting.com/a1b2c3` | `?lng=es` | `bettervoting.com/a1b2c3?lng=es` | +| `bettervoting.com/a1b2c3?id=42` | `&lng=es` | `bettervoting.com/a1b2c3?id=42&lng=es` | ## Why some text is still in English