Add SSR support (#309)

Author: zoontek

README.md

@@ -106,62 +106,64 @@ No setup headaches. Just clean, context-aware translations, out of the box.
 
 ## API
 
-### getLocales()
+### getCalendar()
 
-Returns the user preferred locales, in order.
+Returns the user preferred calendar format.
 
 #### Method type
 
 ```ts
-type getLocales = () => Array<{
-  languageCode: string;
-  scriptCode?: string;
-  countryCode: string;
-  languageTag: string;
-  isRTL: boolean;
-}>;
+type getCalendar = () =>
+  | "gregorian"
+  | "buddhist"
+  | "coptic"
+  | "ethiopic"
+  | "ethiopic-amete-alem"
+  | "hebrew"
+  | "indian"
+  | "islamic"
+  | "islamic-umm-al-qura"
+  | "islamic-civil"
+  | "islamic-tabular"
+  | "iso8601"
+  | "japanese"
+  | "persian";
 ```
 
 #### Usage example
 
 ```ts
-import { getLocales } from "react-native-localize";
+import { getCalendar } from "react-native-localize";
 
-console.log(getLocales());
-/* -> [
-  { countryCode: "GB", languageTag: "en-GB", languageCode: "en", isRTL: false },
-  { countryCode: "US", languageTag: "en-US", languageCode: "en", isRTL: false },
-  { countryCode: "FR", languageTag: "fr-FR", languageCode: "fr", isRTL: false },
-] */
+console.log(getCalendar());
+// -> "gregorian"
 ```
 
 ---
 
-### getNumberFormatSettings()
+### getCountry()
 
-Returns number formatting settings.
+Returns the user current country code (based on its device locale, **not** on its position).
 
 #### Method type
 
 ```ts
-type getNumberFormatSettings = () => {
-  decimalSeparator: string;
-  groupingSeparator: string;
-};
+type getCountry = () => string;
 ```
 
 #### Usage example
 
 ```ts
-import { getNumberFormatSettings } from "react-native-localize";
+import { getCountry } from "react-native-localize";
 
-console.log(getNumberFormatSettings());
-/* -> {
-  decimalSeparator: ".",
-  groupingSeparator: ",",
-} */
+console.log(getCountry());
+// -> "FR"
 ```
 
+#### Note
+
+Devices using Latin American regional settings will return "UN" instead of "419", as the latter is not a standard country code.
+
 ---
 
 ### getCurrencies()
@@ -185,62 +187,60 @@ console.log(getCurrencies());
 
 ---
 
-### getCountry()
+### getLocales()
 
-Returns the user current country code (based on its device locale, **not** on its position).
+Returns the user preferred locales, in order.
 
 #### Method type
 
 ```ts
-type getCountry = () => string;
+type getLocales = () => Array<{
+  languageCode: string;
+  scriptCode?: string;
+  countryCode: string;
+  languageTag: string;
+  isRTL: boolean;
+}>;
 ```
 
 #### Usage example
 
 ```ts
-import { getCountry } from "react-native-localize";
+import { getLocales } from "react-native-localize";
 
-console.log(getCountry());
-// -> "FR"
+console.log(getLocales());
+/* -> [
+  { countryCode: "GB", languageTag: "en-GB", languageCode: "en", isRTL: false },
+  { countryCode: "US", languageTag: "en-US", languageCode: "en", isRTL: false },
+  { countryCode: "FR", languageTag: "fr-FR", languageCode: "fr", isRTL: false },
+] */
 ```
 
-#### Note
-
-Devices using Latin American regional settings will return "UN" instead of "419", as the latter is not a standard country code.
-
 ---
 
-### getCalendar()
+### getNumberFormatSettings()
 
-Returns the user preferred calendar format.
+Returns number formatting settings.
 
 #### Method type
 
 ```ts
-type getCalendar = () =>
-  | "gregorian"
-  | "buddhist"
-  | "coptic"
-  | "ethiopic"
-  | "ethiopic-amete-alem"
-  | "hebrew"
-  | "indian"
-  | "islamic"
-  | "islamic-umm-al-qura"
-  | "islamic-civil"
-  | "islamic-tabular"
-  | "iso8601"
-  | "japanese"
-  | "persian";
+type getNumberFormatSettings = () => {
+  decimalSeparator: string;
+  groupingSeparator: string;
+};
 ```
 
 #### Usage example
 
 ```ts
-import { getCalendar } from "react-native-localize";
+import { getNumberFormatSettings } from "react-native-localize";
 
-console.log(getCalendar());
-// -> "gregorian"
+console.log(getNumberFormatSettings());
+/* -> {
+  decimalSeparator: ".",
+  groupingSeparator: ",",
+} */
 ```
 
 ---
@@ -382,7 +382,7 @@ Returns the best language tag possible and its reading direction. Useful to pick
 ```ts
 type findBestLanguageTag = (
   languageTags: string[],
-) => { languageTag: string; isRTL: boolean } | void;
+) => { languageTag: string; isRTL: boolean } | undefined;
 ```
 
 #### Usage example
@@ -420,6 +420,41 @@ openAppLanguageSettings("application").catch((error) => {
 });
 ```
 
+## Server-side rendering
+
+On the client, `react-native-localize` uses `navigator.languages`. During SSR, it gets language preferences from the server via the parsed `Accept-Language` header.
+
+#### 1. Wrap your app with `ServerLanguagesProvider`
+
+On the server, wrap your app with `ServerLanguagesProvider` and pass the user's languages:
+
+```tsx
+import accepts from "accepts";
+import { ServerLanguagesProvider } from "react-native-localize";
+
+// parse the Accept-Language header; any approach returning string[] is fine
+const languages = accepts(request).languages();
+
+const html = renderToString(
+  <ServerLanguagesProvider value={languages}>
+    <App />
+  </ServerLanguagesProvider>,
+);
+```
+
+#### 2. Use the `useLocalize` hook in your components
+
+In your components, use the `useLocalize` hook instead of calling the API methods directly:
+
+```tsx
+import { useLocalize } from "react-native-localize";
+
+const App = () => {
+  const { getCountry } = useLocalize();
+  return <Text>Country: {getCountry()}</Text>;
+};
+```
+
 ## Examples with [@formatjs/intl](https://formatjs.io/docs/intl)
 
 Browse the files in the [/example](https://github.com/zoontek/react-native-localize/tree/master/example) directory.

docs/screenshot.png

@@ -1,5 +1,4 @@
 import { createIntl, createIntlCache } from "@formatjs/intl";
-import * as React from "react";
 import {
   Button,
   I18nManager,
@@ -9,7 +8,21 @@ import {
   Text,
   View,
 } from "react-native";
-import * as Localize from "react-native-localize";
+import {
+  findBestLanguageTag,
+  getCalendar,
+  getCountry,
+  getCurrencies,
+  getLocales,
+  getNumberFormatSettings,
+  getTemperatureUnit,
+  getTimeZone,
+  openAppLanguageSettings,
+  uses24HourClock,
+  usesAutoDateAndTime,
+  usesAutoTimeZone,
+  usesMetricSystem,
+} from "react-native-localize";
 import {
   SafeAreaProvider,
   useSafeAreaInsets,
@@ -27,7 +40,7 @@ type Translation = keyof typeof translations;
 const fallback = { languageTag: "en", isRTL: false };
 
 const { languageTag, isRTL } =
-  Localize.findBestLanguageTag(Object.keys(translations)) ?? fallback;
+  findBestLanguageTag(Object.keys(translations)) ?? fallback;
 
 // update layout direction
 I18nManager.forceRTL(isRTL);
@@ -93,53 +106,31 @@ const AppContent = () => {
         },
       ]}
     >
-      <Line name="Localize.getLocales()" value={Localize.getLocales()} />
-
-      <Line name="Localize.getCurrencies()" value={Localize.getCurrencies()} />
-
-      <Line name="Localize.getCountry()" value={Localize.getCountry()} />
-
-      <Line name="Localize.getCalendar()" value={Localize.getCalendar()} />
-
-      <Line
-        name="Localize.getNumberFormatSettings()"
-        value={Localize.getNumberFormatSettings()}
-      />
+      <Line name="getCalendar()" value={getCalendar()} />
+      <Line name="getCountry()" value={getCountry()} />
+      <Line name="getCurrencies()" value={getCurrencies()} />
+      <Line name="getLocales()" value={getLocales()} />
 
       <Line
-        name="Localize.getTemperatureUnit()"
-        value={Localize.getTemperatureUnit()}
+        name="getNumberFormatSettings()"
+        value={getNumberFormatSettings()}
       />
 
-      <Line name="Localize.getTimeZone()" value={Localize.getTimeZone()} />
-
-      <Line
-        name="Localize.uses24HourClock()"
-        value={Localize.uses24HourClock()}
-      />
-
-      <Line
-        name="Localize.usesMetricSystem()"
-        value={Localize.usesMetricSystem()}
-      />
+      <Line name="getTemperatureUnit()" value={getTemperatureUnit()} />
+      <Line name="getTimeZone()" value={getTimeZone()} />
+      <Line name="uses24HourClock()" value={uses24HourClock()} />
+      <Line name="usesMetricSystem()" value={usesMetricSystem()} />
 
       {Platform.OS === "android" && (
         <>
-          <Line
-            name="Localize.usesAutoDateAndTime()"
-            value={Localize.usesAutoDateAndTime()}
-          />
-
-          <Line
-            name="Localize.usesAutoTimeZone()"
-            value={Localize.usesAutoTimeZone()}
-          />
+          <Line name="usesAutoDateAndTime()" value={usesAutoDateAndTime()} />
+          <Line name="usesAutoTimeZone()" value={usesAutoTimeZone()} />
         </>
       )}
 
       <Line
-        name="Localize.findBestLanguageTag(['en-US', 'en', 'fr'])"
-        value={Localize.findBestLanguageTag(["en-US", "en", "fr"])}
+        name="findBestLanguageTag(['en-US', 'en', 'fr'])"
+        value={findBestLanguageTag(["en-US", "en", "fr"])}
       />
 
       <Line name="Translation example" value={translate("hello")} />
@@ -148,7 +139,7 @@ const AppContent = () => {
         <Button
           title="Open app language settings"
           onPress={() => {
-            Localize.openAppLanguageSettings().catch((error) => {
+            openAppLanguageSettings().catch((error) => {
               console.error(error);
             });
           }}

example/src/App.tsx

@@ -1,12 +1,12 @@
 // http://necolas.github.io/react-native-web/docs/?path=/docs/guides-multi-platform--page#web-packaging-for-existing-react-native-apps
 
 const path = require("path");
-const fromRoot = (_) => path.resolve(__dirname, _);
 
-const isProd = process.env.NODE_ENV === "production";
+const fromRoot = (_) => path.resolve(__dirname, _);
+const nodeModules = fromRoot("node_modules");
 
 module.exports = {
-  mode: isProd ? "production" : "development",
+  mode: process.env.NODE_ENV === "production" ? "production" : "development",
   entry: fromRoot("index.js"),
   output: {
     path: fromRoot("dist"),
@@ -26,7 +26,11 @@ module.exports = {
     ],
   },
   resolve: {
-    alias: { "react-native$": "react-native-web" },
+    alias: {
+      react: path.join(nodeModules, "react"),
+      "react-dom": path.join(nodeModules, "react-dom"),
+      "react-native$": "react-native-web",
+    },
     extensions: [".ts", ".tsx", ".js", ".jsx", ".json"]
       .map((extension) => [".web" + extension, extension])
       .flat(),