@fluid-app/fluid-cli-localization 0.1.0

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.
Files changed (6) hide show
  1. package/README.md +179 -0
  2. package/dist/index.d.mts +20 -0
  3. package/dist/index.d.mts.map +1 -0
  4. package/dist/index.mjs +3965 -0
  5. package/dist/index.mjs.map +1 -0
  6. package/package.json +84 -0
package/README.md ADDED
@@ -0,0 +1,179 @@
1
+ # @fluid-app/fluid-cli-localization
2
+
3
+ Fluid CLI plugin for selling in another country and in another language. It
4
+ adds two command groups:
5
+
6
+ - `fluid countries` opens a country from Fluid's Country Atlas, converts your
7
+ prices into its currency, creates its agreements, and checks the result.
8
+ - `fluid translations` turns languages on, reports what shoppers would still
9
+ see untranslated, machine-translates it with Fluid AI, and writes it back.
10
+
11
+ The country flow hands language work to `fluid translations`, so each step
12
+ has one command.
13
+
14
+ ```bash
15
+ npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-localization
16
+ fluid login
17
+
18
+ # Open a country
19
+ fluid countries atlas DE # the atlas: modes, tax, legal, address, payments, languages
20
+ fluid countries plan DE --mode otg # preview, changes nothing
21
+ fluid countries open DE --mode otg --yes # add the country, seeded from the atlas
22
+ fluid countries prices DE # preview converting US prices into EUR
23
+ fluid countries prices DE --rate 0.92 --write --yes
24
+ fluid countries languages DE # which market languages are off, and the command to turn them on
25
+ fluid translations enable de --yes
26
+ fluid countries agreements DE --create --yes # the atlas agreements, in every atlas language
27
+ fluid countries status DE # check against the atlas
28
+
29
+ # Translate
30
+ fluid translations missing de # what isn't translated yet, per type
31
+ fluid translations auto de --limit 10 # machine-translate 10 per type, print only
32
+ fluid translations auto de --limit 25 --write --yes
33
+ fluid translations set products 60311 --lang de --yes --set title="Rote-Bete-Mischung"
34
+ ```
35
+
36
+ Every command prints JSON. Failures print a JSON `error` on stderr and exit
37
+ non-zero. Commands that change live configuration, prices or content ask for
38
+ confirmation unless you pass `--yes`.
39
+
40
+ ## Walks
41
+
42
+ Both groups have a `walk` that asks questions in a terminal instead of
43
+ taking flags. Type `<` to go back, `>` to skip, `?` for the menu, and Ctrl-C
44
+ to stop. Each walk saves through the same calls as the commands, and scripts
45
+ and agents use the commands instead.
46
+
47
+ - `fluid countries walk [iso]` opens a country the way Mist does. It asks for
48
+ the country (searchable) and shows its atlas, then asks the operating mode
49
+ (each explained in one line), the warehouse, which market languages to
50
+ turn on, which atlas agreements to create or translate, and whether to keep
51
+ or change each atlas default: currency, tax, 3-D Secure, payment order and
52
+ address layout. Then it asks whether to add Fluid's generic defaults and
53
+ shows a summary to confirm. Nothing is saved before you confirm. It then
54
+ opens the country, turns on the languages, and creates the agreements. Next
55
+ it offers the price conversion: it shows the numbers and a sample at the
56
+ rate you give and saves only on a yes. Finally it hands each market language
57
+ to the translations walk.
58
+ - `fluid translations walk [iso]` asks for the language if you don't name
59
+ one, offering to turn it on. It shows what's missing per type, then lets you
60
+ machine-translate each type in batches. You go through the proposals one at
61
+ a time to accept, edit or skip, and each one is saved as you accept it. It
62
+ covers every type, including theme strings and theme page strings.
63
+
64
+ ## `fluid countries`
65
+
66
+ | Command | What it does |
67
+ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68
+ | `atlas <iso>` | The atlas for a market, without the agreement legal text. `--agreement <localId>` prints one agreement in full. |
69
+ | `compliance <iso>` | Disclosure pages, cookie rule, tax display and unit pricing from the atlas. |
70
+ | `list` | The countries the company sells in. |
71
+ | `plan <iso> --mode <m>` | What `open` would send, with language and agreement status, warehouses and the launch checklist. Read-only. |
72
+ | `open <iso> --mode <m>` | Adds the country, seeded from the atlas: currency, mode, tax name, tax-inclusive pricing, tax invoices, 3-D Secure, legal settings, address layout and payment method order. |
73
+ | `prices <iso>` | Converts each variant's price from another country (`--from-country`, default `US`) into this country's currency. A dry run unless `--write`. |
74
+ | `languages <iso>` | The market's major languages and whether each is on, with the `fluid translations enable` command for the ones that are off. |
75
+ | `agreements <iso>` | Atlas agreements matched to the company's by title. `--create` adds the missing ones; `--translate` writes the atlas translations onto ones already on the country. |
76
+ | `status <iso>` | Compares the country with the atlas, checks that every variant of your active products has a price there and something is on sale, then lists the price and translation commands to run and the work left for a person. |
77
+
78
+ `open` takes `--warehouse-id`, `--business-id`, `--entity-registered` and
79
+ `--settlement-currency` for what the atlas can't know, and `--set key=value`
80
+ to override a seeded value. It skips Fluid's generic country agreements and
81
+ forms (pass `--legacy-defaults` to keep them), and changes nothing on an open
82
+ country unless you pass `--reseed`.
83
+
84
+ ### Converting prices
85
+
86
+ `fluid countries prices DE` reads every active product (`--status` for
87
+ others) and, for each variant, multiplies its US price by the rate and rounds
88
+ it half up to the currency's minor unit (whole units for JPY, KRW and the
89
+ other zero-decimal currencies, cents for the rest). It prints the rate, the
90
+ rounding, counts, and a sample of before and after prices. Nothing is saved.
91
+
92
+ - **Rate.** Pass `--rate`: units of the new currency per unit of the source
93
+ currency. Without it, the preview uses the European Central Bank's daily
94
+ reference rate. `--write` always needs `--rate`, so the rate saved is the
95
+ one you reviewed.
96
+ - **Fields.** `price`, `subscription_price` and `compare_price` by default.
97
+ Add `wholesale` and `wholesale_subscription_price` with `--fields`. A field
98
+ with no source amount is left alone.
99
+ - **Never free.** A variant whose converted price rounds to zero is skipped
100
+ (`roundsToZero`), and any other field that rounds to zero is left out.
101
+ - **Reruns are safe.** A variant that already has a price in the country is
102
+ skipped (`alreadyPriced`), so a second run never converts a converted price.
103
+ A price saved in another currency is skipped too (`pricedInOtherCurrency`).
104
+ `--overwrite` replaces both.
105
+ - **On sale.** Converted prices keep the variant's current on-sale state in
106
+ the country. `--activate` puts each converted variant on sale.
107
+ - **Failures.** Each variant is saved on its own. A refused save is listed
108
+ under `failed` with the API's message, and the rest carry on.
109
+ - **Changes during the run.** Each product is read again just before its
110
+ variants are saved. A variant that someone priced in the country since the
111
+ preview is left alone and listed under `changedSincePreview`.
112
+ - **Price editor.** When the price editor manages the company's prices,
113
+ `priceEditor` is `true`. Each save then goes into the price editor's price
114
+ lists; one it can't place is listed with `refusedByPriceEditor: true`.
115
+ `--overwrite` is refused for these companies, so a price someone set in the
116
+ price editor is never replaced from here.
117
+
118
+ ## `fluid translations`
119
+
120
+ | Command | What it does |
121
+ | ------------------------------------------------ | --------------------------------------------------------------------------------- |
122
+ | `languages` | Every language Fluid supports, and whether it's on. |
123
+ | `enable <iso...>` / `disable <iso>` | Turn languages on or off. |
124
+ | `types` | The translatable types and their fields. |
125
+ | `missing <iso>` | What isn't translated yet, per type. `done` is `true` when nothing is. |
126
+ | `show <type> <id> --lang <iso>` | One item's default text beside its translation. |
127
+ | `set <type> [id] --lang <iso> --set field=value` | Save a translation by hand. `--file` takes a JSON object for long or HTML values. |
128
+ | `auto <iso>` | Machine-translate what's missing with Fluid AI. `--write` saves it. |
129
+
130
+ | Type | Fields | Counts as translated when |
131
+ | ------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------ |
132
+ | `products` | title, introduction, description, feature_text, image_url | the row's `languages` lists the language |
133
+ | `categories`, `collections`, `pages`, `playlists` | title, description, image_url | the same |
134
+ | `posts` | title, description, summary, image_url | the same |
135
+ | `media` | title, description, image_url, video_url, pdf_url | the same |
136
+ | `enrollment-packs` | title, description | the same |
137
+ | `menu-items` | title | the title has a value in the language |
138
+ | `theme` | every string in `locales/<iso>.json` | the key has a non-blank value |
139
+ | `theme-sections` | a page template's own strings, which override the locale files on that page | the key has a non-blank value in the template's translations |
140
+ | `agreements` | title and description, saved together | a read in the language is served in it |
141
+ | `labels` | title (product badges you created) | its title in the language differs from the default |
142
+
143
+ Notes:
144
+
145
+ - `auto` translates storefront rows, menu items, agreements and labels from
146
+ the store's default language, read from the storefront rows
147
+ (`--store-language` only when it can't be read). Theme strings translate
148
+ from the `--from` locale, `en` by default. An item the translator returns
149
+ only part of is listed under `incomplete` and not saved; `--skip <type>:<id>`
150
+ leaves it out of later runs. Items the API refuses are listed under
151
+ `failed`. Both count toward `remaining`.
152
+ - A storefront row with any translation counts as translated, because reads
153
+ fall back to the default for fields without one.
154
+ - A label whose translation is the same word as the default (a brand name)
155
+ stays listed; skip it with `--skip labels:<id>`.
156
+ - `missing` lists theme keys whose value is still word for word the source
157
+ under `sameAsSource`, to review by eye.
158
+ - Theme writes publish immediately. A locale file write sends the theme
159
+ version it read, so a concurrent edit makes it fail instead of
160
+ overwriting; `auto` lists every key of a refused write under `failed`. A
161
+ theme whose files can't be listed (an invalid member configuration) can be
162
+ read but not saved, because the write couldn't be guarded. A theme-sections
163
+ write reads the template again just before saving and merges into it.
164
+
165
+ ## Not covered
166
+
167
+ These have no API that translates them, so they stay in fluid-admin or with a
168
+ person:
169
+
170
+ - Promotions (title, description, terms).
171
+ - Enrollment form fields and their labels, and forms.
172
+ - Fluid's own labels ("New", "Trending"), which Fluid translates.
173
+ - Section settings written as literal text rather than as a locale key. Use
174
+ the page editor's translate mode, which turns the setting into a key, then
175
+ `fluid translations` covers it.
176
+ - Payment provider onboarding and the launch checklist for a country.
177
+
178
+ The walkthroughs are the "Open a country" and "Add a language" guided setups
179
+ at https://docs.fluid.app/setup.
package/dist/index.d.mts ADDED
@@ -0,0 +1,20 @@
1
+ import { CommandContext, FluidPlugin } from "@fluid-app/fluid-cli";
2
+ import { Command } from "commander";
3
+
4
+ //#region src/countries/commands.d.ts
5
+ declare function registerCountriesCommands(parent: Command, ctx: CommandContext): void;
6
+ //#endregion
7
+ //#region src/translations/commands.d.ts
8
+ declare function registerTranslationsCommands(parent: Command, ctx: CommandContext): void;
9
+ //#endregion
10
+ //#region src/index.d.ts
11
+ /**
12
+ * One plugin, two command groups: `fluid countries` opens a market and
13
+ * `fluid translations` translates what its shoppers see. The country flow
14
+ * hands language and translation work to `fluid translations`, so each step
15
+ * has one implementation.
16
+ */
17
+ declare const plugin: FluidPlugin;
18
+ //#endregion
19
+ export { plugin as default, registerCountriesCommands, registerTranslationsCommands };
20
+ //# sourceMappingURL=index.d.mts.map
package/dist/index.d.mts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/countries/commands.ts","../src/translations/commands.ts","../src/index.ts"],"mappings":";;;;iBA6JgB,yBAAA,CACd,MAAA,EAAQ,OAAA,EACR,GAAA,EAAK,cAAA;;;iBC/DS,4BAAA,CACd,MAAA,EAAQ,OAAA,EACR,GAAA,EAAK,cAAA;;;;AD2DP;;;;;cE9IM,MAAA,EAAQ,WAAA"}