@schematichq/schematic-components 2.25.2 → 2.27.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
@@ -35,7 +35,7 @@ const { initializeWithPlan } = useEmbed();
35
35
  This function allows developers to create their own button that
36
36
 
37
37
  * Pre-selects a Plan
38
- * Pre-selects Add-ons (if available)
38
+ * Pre-selects add-ons (if available)
39
39
  * Skips and hides plan selection stages
40
40
 
41
41
  The `initializeWithPlan` function can be called with a Schematic plan ID, or
@@ -48,13 +48,13 @@ selection stage.
48
48
  initializeWithPlan('plan_VBXv4bHjSf3');
49
49
  ```
50
50
 
51
- Passing a config object allows pre-selecting Add-ons and pay-in-advance
51
+ Passing a config object allows pre-selecting add-ons and pay-in-advance
52
52
  quantities, as well as hiding specific stages.
53
53
 
54
54
  ```ts
55
55
  const config = {
56
56
  planId: 'plan_VBXv4bHjSf3', // pre-select a Plan
57
- addOnIds: ['plan_AWv7bPjSx2'], // pre-select 1 or more Add-ons
57
+ addOnIds: ['plan_AWv7bPjSx2'], // pre-select 1 or more add-ons
58
58
  period: 'month', // pre-select 'month' or 'year' for the billing period (optional)
59
59
  payInAdvanceQuantities: { // pre-fill pay-in-advance quantities, keyed by feature id (optional)
60
60
  feat_cns2asuKAG2: 3, // "feat_cns2asuKAG2" is a feature id, 3 is the quantity
@@ -90,7 +90,7 @@ you unsubscribe." It is shown by default; set it to `false` when your own UI
90
90
  states the billing terms. Hiding it does not affect the scheduled-downgrade
91
91
  notice that appears in the same spot.
92
92
 
93
- The Plans and Add-ons available to the checkout flows must be live in your
93
+ The Plans and add-ons available to the checkout flows must be live in your
94
94
  Schematic account [Catalog configuration](https://docs.schematichq.com/catalog/overview).
95
95
 
96
96
  ## Programmatic Unsubscribe
@@ -119,6 +119,64 @@ The unsubscribe flow is rendered by the embed itself, so a Schematic embed (the
119
119
  `Viewport` that hosts it) must be mounted on the page where you call
120
120
  `requestUnsubscribe`. This is the same requirement as `initializeWithPlan`.
121
121
 
122
+ ## Localization
123
+
124
+ The components render in English by default. `EmbedProvider` takes three props
125
+ to change that:
126
+
127
+ ```tsx
128
+ <EmbedProvider
129
+ accessToken={accessToken}
130
+ i18n={i18next}
131
+ translations={{ it: schematicIt }}
132
+ locale="it-IT"
133
+ >
134
+ ```
135
+
136
+ - `locale` is a BCP 47 tag. It picks the language the components read from and
137
+ formats every number, currency, and date. Without it, the components use the
138
+ `i18n` instance's current language, else `en-US`.
139
+ - `i18n` is your own i18next instance, v21 or later. The components read their
140
+ strings from its `schematic` namespace in its current language, and re-render
141
+ when you call `changeLanguage`. Nothing is fetched from your backend: the
142
+ components look keys up and fall back to English for any they do not find.
143
+ - `translations` is a map of language to bundle, for an app without i18next. Any
144
+ key a bundle leaves out falls back to English.
145
+
146
+ Keys are the English strings themselves, and the English bundle is exported as
147
+ `schematicTranslationsEn` to translate from. The `SchematicTranslations` type
148
+ checks a bundle's keys. A plural takes i18next's suffixes, looked up by the bare
149
+ key and a `count`:
150
+
151
+ ```ts
152
+ import type { SchematicTranslations } from '@schematichq/schematic-components';
153
+
154
+ export const schematicIt: SchematicTranslations = {
155
+ 'Cancel subscription': 'Annulla abbonamento',
156
+ 'Discount for months_one': '{{discount}} per il prossimo mese',
157
+ 'Discount for months_other': '{{discount}} per i prossimi {{count, number}} mesi',
158
+ };
159
+ ```
160
+
161
+ With an `i18n` instance, register the same bundle under the `schematic`
162
+ namespace:
163
+
164
+ ```ts
165
+ i18next.addResourceBundle('it', 'schematic', schematicIt);
166
+ ```
167
+
168
+ Passing both `i18n` and `translations` is unusual. If you do, the instance
169
+ answers first, including through its own `fallbackLng`, so a key its English
170
+ bundle has is never read from `translations`.
171
+
172
+ Numbers interpolated into a string are formatted for the locale before they
173
+ reach it, so `{{amount}}` reads `20,000` or `20.000` on its own. A plural's
174
+ `count` is the exception: it stays a number so i18next can pick the form, and
175
+ the bundle formats it with `{{count, number}}`.
176
+
177
+ Feature names and their plural forms come from your Schematic account, not the
178
+ bundle, so set them there in the language you need.
179
+
122
180
  ## License
123
181
 
124
182
  MIT