aa-geuthur-react 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -82,19 +82,24 @@ import "@/Styles/index.css";
82
82
 
83
83
  ### Translations<a name="translations"></a>
84
84
 
85
- Every text of the package lives in the i18next namespace `aa-geuthur-react`. The package ships `i18n/<lng>/aa-geuthur-react.json` for 12 languages (`en`, `de`, `es`, `fr-FR`, `it-IT`, `ja`, `ko-KR`, `nl-NL`, `pl-PL`, `ru`, `uk`, `zh-Hans`). The app copies the file next to its own `translation.json` into the static directory and loads namespaces by name:
85
+ Every text of the package lives in the i18next namespace `aa-geuthur-react` and is bundled into the package. `AaReactProvider` registers the translations with the i18next instance of the app when it mounts (`addResourceBundle`, texts the app already has for the namespace are kept), so the app lists only its own namespace and copies nothing. Untranslated texts are empty strings, so set `returnEmptyString: false` and i18next falls back to English:
86
86
 
87
87
  ```ts
88
88
  i18n.use(Backend).use(initReactI18next).init({
89
- ns: ["translation", "aa-geuthur-react"],
89
+ lng: djangoLanguage,
90
+ fallbackLng: "en",
91
+ ns: ["translation"],
90
92
  defaultNS: "translation",
93
+ returnEmptyString: false,
91
94
  backend: {
92
95
  loadPath: `/static/${ProjectName}/i18n/{{lng}}/{{ns}}.json`,
93
96
  },
94
97
  });
95
98
  ```
96
99
 
97
- The constants `I18N_NAMESPACE` (`aa-geuthur-react`) and `I18N_FALLBACK_NAMESPACE` (`translation`) are exported. Menu link names come from the app, so the menu tries the package namespace first and the namespace of the app second.
100
+ The constants `I18N_NAMESPACE` (`aa-geuthur-react`) and `I18N_FALLBACK_NAMESPACE` (`translation`) are exported. Menu link names come from the app, so the menu tries the package namespace first and the namespace of the app second. `registerI18nResources(i18n)` adds the translations to an instance outside of the provider, e.g. in a test.
101
+
102
+ The source files `i18n/<lng>/aa-geuthur-react.json` (12 languages: `en`, `de`, `es`, `fr-FR`, `it-IT`, `ja`, `ko-KR`, `nl-NL`, `pl-PL`, `ru`, `uk`, `zh-Hans`) are translated in [Weblate](https://weblate.geuthur.de/projects/allianceauth/aa-geuthur-react/); `en` is the template with key equal value, `make translations` adds new keys empty to every other language. They stay exported as `aa-geuthur-react/i18n/<lng>/aa-geuthur-react.json`.
98
103
 
99
104
  ### API client<a name="api-client"></a>
100
105
 
@@ -7,7 +7,10 @@ export interface AaReactConfig {
7
7
  /** Interval in milliseconds in which `useMenu` reloads the menu (badges stay live). Off by default. */
8
8
  menuRefetchInterval?: number;
9
9
  }
10
- /** Provides the app names to the menus, hooks and pages of this package. Wrap the routing with it. */
10
+ /**
11
+ * Provides the app names to the menus, hooks and pages of this package and registers the
12
+ * translations of the package with the i18next instance of the app. Wrap the routing with it.
13
+ */
11
14
  export declare function AaReactProvider({ projectName, appName, menuRefetchInterval, children, }: AaReactConfig & {
12
15
  children?: ReactNode;
13
16
  }): import('react').JSX.Element;
package/dist/i18n.d.ts CHANGED
@@ -1,4 +1,16 @@
1
- /** i18next namespace of every text in this package. The apps load it from `i18n/<lng>/aa-geuthur-react.json`. */
1
+ import { i18n as I18n } from 'i18next';
2
+ /**
3
+ * i18next namespace of every text in this package. `AaReactProvider` registers the translations
4
+ * with the i18next instance of the app, the app itself loads nothing for this namespace.
5
+ */
2
6
  export declare const I18N_NAMESPACE = "aa-geuthur-react";
3
7
  /** Namespace of the app that is tried after the package namespace, e.g. for menu link names. */
4
8
  export declare const I18N_FALLBACK_NAMESPACE = "translation";
9
+ /**
10
+ * Adds the bundled translations of this package to an initialized i18next instance, once per instance.
11
+ * `AaReactProvider` calls it on mount. Existing texts of the namespace are kept, so an app can
12
+ * override single texts with its own resources. Untranslated texts are empty strings; the app sets
13
+ * `returnEmptyString: false` so they fall back to `fallbackLng`. Does nothing without an
14
+ * initialized instance (e.g. when `react-i18next` is mocked in a test).
15
+ */
16
+ export declare function registerI18nResources(i18n: I18n | undefined): void;
@@ -0,0 +1,2 @@
1
+ /** `{ de: { Close: "" }, en: { Close: "Close" }, … }` keyed by the directory name of the file. */
2
+ export declare const i18nResources: Record<string, Record<string, string>>;