frontend/i18n: lang=... query parameter, refactor setLocale initialization

Author: haraldschilly

src/packages/frontend/app/page.tsx

@@ -27,7 +27,7 @@ import { Loading } from "@cocalc/frontend/components";
 import { IconName } from "@cocalc/frontend/components/icon";
 import { SiteName } from "@cocalc/frontend/customize";
 import { FileUsePage } from "@cocalc/frontend/file-use/page";
-import { getLocale, labels, Locale } from "@cocalc/frontend/i18n";
+import { labels } from "@cocalc/frontend/i18n";
 import { ProjectsNav } from "@cocalc/frontend/projects/projects-nav";
 import PayAsYouGoModal from "@cocalc/frontend/purchases/pay-as-you-go/modal";
 import openSupportTab from "@cocalc/frontend/support/open";
@@ -38,7 +38,6 @@ import { ConnectionIndicator } from "./connection-indicator";
 import { ConnectionInfo } from "./connection-info";
 import { useAppContext } from "./context";
 import { FullscreenButton } from "./fullscreen-button";
-import { useLocalizationCtx } from "./localize";
 import { AppLogo } from "./logo";
 import { NavTab } from "./nav-tab";
 import { Notification } from "./notifications";
@@ -76,7 +75,6 @@ export const Page: React.FC = () => {
   const { isNarrow, fileUseStyle, topBarStyle, projectsNavStyle } = pageStyle;
 
   const intl = useIntl();
-  const { setLocale } = useLocalizationCtx();
 
   const open_projects = useTypedRedux("projects", "open_projects");
   const [show_label, set_show_label] = useState<boolean>(true);
@@ -105,7 +103,6 @@ export const Page: React.FC = () => {
   const account_id = useTypedRedux("account", "account_id");
   const is_logged_in = useTypedRedux("account", "is_logged_in");
   const is_anonymous = useTypedRedux("account", "is_anonymous");
-  const other_settings = useTypedRedux("account", "other_settings");
   const doing_anonymous_setup = useTypedRedux(
     "account",
     "doing_anonymous_setup",
@@ -115,11 +112,6 @@ export const Page: React.FC = () => {
 
   const is_commercial = useTypedRedux("customize", "is_commercial");
 
-  useEffect(() => {
-    const i18n: Locale = getLocale(other_settings);
-    setLocale(i18n);
-  }, []);
-
   function account_tab_icon(): IconName | JSX.Element {
     if (is_anonymous) {
       return <></>;

src/packages/frontend/app/render.tsx

@@ -6,13 +6,51 @@
 import ReactDOM from "react-dom";
 import { createRoot } from "react-dom/client";
 
-import { Redux } from "@cocalc/frontend/app-framework";
+import {
+  redux,
+  Redux,
+  useEffect,
+  useTypedRedux,
+} from "@cocalc/frontend/app-framework";
+import {
+  getLocale,
+  Locale,
+  LOCALIZATIONS,
+  OTHER_SETTINGS_LOCALE_KEY,
+} from "@cocalc/frontend/i18n";
+import { QueryParams } from "@cocalc/frontend/misc/query-params";
 import { AppContext, useAppContextProvider } from "./context";
-import { Localize } from "./localize";
+import { Localize, useLocalizationCtx } from "./localize";
 
 // App uses the context provided by Redux (for the locale, etc.) and Localize.
 function App({ children }) {
   const appState = useAppContextProvider();
+  const { setLocale } = useLocalizationCtx();
+  const other_settings = useTypedRedux("account", "other_settings");
+
+  useEffect(() => {
+    const lang = QueryParams.get("lang");
+    if (lang != null) {
+      if (lang in LOCALIZATIONS) {
+        console.warn(
+          `URL query parameter 'lang=${lang}' – overriding user configuration.`,
+        );
+        redux
+          .getActions("account")
+          .set_other_settings(OTHER_SETTINGS_LOCALE_KEY, lang);
+        setLocale(lang);
+      } else {
+        console.warn(
+          `URL query parameter 'lang=${lang}' provided, but not a valid locale.`,
+          `Known values: ${Object.keys(LOCALIZATIONS)}`,
+        );
+      }
+    } else {
+      const i18n: Locale = getLocale(other_settings);
+      setLocale(i18n);
+    }
+  }, [other_settings]);
+
   return <AppContext.Provider value={appState}>{children}</AppContext.Provider>;
 }
 

src/packages/frontend/i18n/README.md

@@ -1,6 +1,8 @@
 # I18N in CoCalc
 
-Define messages directly in the component or use `./common.ts` for shared messages, etc. Search for e.g. `labels.projects` to see how they are used. This is only for the frontend – the Next.js part could be done similar, but needs a separate workflow.
+## Development
+
+Define messages directly in the component or use `./common.ts` for shared messages, etc. Search for e.g. `labels.projects` to see how they are used. This is only for the frontend – the Next.js part could be done similarly, but needs a separate workflow.
 
 `frontend/package.json` has three script entries, which are for [SimpleLocalize](https://simplelocalize.io/).
 
@@ -42,10 +44,18 @@ CoCalc specific rules for implementing translations, of which I think are good t
 
 - **Explicit ID**: Technically, the ID is optional. Then it is computed as a hash upon extraction. However, this has two negative sides:
   - If the message changes, it's hash changes, and you have to start over with the translation. This is good from an idealistic standpoint, but if you just tweak a word or correct a typo, the existing translations are still ok. If the meaning changes completely, it's better to create a new ID. (Of course, changes to the `defaultMessage` need to go through the `extract → upload` step, except that the English translation uses the `defaultMessage` directly.)
-  - Sorting: All the translations and also online tools like SimpleLocalize sort the translations by their keys. Look at the translated `i18n/de_DE.json` and you'll see, that messages that are related are also next to each other. This also makes it possible to filter for a specific
+  - Sorting: All the translations and also online tools like SimpleLocalize sort the translations by their keys. Look at the translated `i18n/de_DE.json` and you'll see that messages that are related are also next to each other. This also makes it possible to filter for a specific
 - Pitfall **No variables in properties**: I think the extraction process does not know how to deal with variables, when extracting strings from properties. So, either define the message objects elsewhere (like it is done with `labels`) or write a multiline string in place. See the examples below for what works.
 - **No `en` translation**: English is the default. The `defaultMessage` is already in the code. We do not download the supposedly translated `en` file and just let the fallback mechanism kick in. This also means that changes to the `defaultMessage` will show up with the next build, even without touching any of the translations.
 - **richTextElements**: in `app/localize.tsx`, a few default `richTextElements` are defined – just for convenience. Anchor tags must be defined individually, because link text and href can't be wrapped that way.
+- **Query parameter**: A new `?lang=en` (or `=de`, `=zh`, ...) query parameters lets you change the language as well. This also changes the account setting. Hence, a URL with `?lang=en` can be used to reset the account setting to English.
+
+## Style
+
+We discussed this internally on 2024-08-19 and came to the conclusion that we should not overdo translations.
+
+- Example: translating the "Run" button in Jupyter to German or Russian, which both have more or less the meaning of "running in the street", is extremely awkward. It's also a well recognizable element, which users are used to, even without knowing what it really means. Therefore, we do not translate elements like the "Run" button.
+- However, what we should translate (or add) are hover text explanations. So, in the case of the "Run" button, there should be a tooltip, which explains in the current language, what this button really does.
 
 ## Examples
 
@@ -119,7 +129,7 @@ force_build: {
 }
 ```
 
-The `ManageCommands` class knows what to do with that. If you use a function to deinfe a label or title,
+The `ManageCommands` class knows what to do with that. If you use a function to define a label or title,
 the `intl` (`IntlShape`) object is passed in as well.
 
 ```typescript

src/packages/frontend/misc/misc.ts

@@ -3,8 +3,8 @@
  *  License: MS-RSL – see LICENSE.md for details
  */
 
-import { QueryParams } from "../misc/query-params";
 import target from "@cocalc/frontend/client/handle-target";
+import { QueryParams } from "@cocalc/frontend/misc/query-params";
 
 declare var $: any;