Skip to content

Commit bdfbb2d

Browse files
robrechtmerobrechtme
committed
docs: add docs website
1 parent ffbbc43 commit bdfbb2d

18 files changed

Lines changed: 4522 additions & 188 deletions

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,10 @@ out
88

99
# Env
1010
.env
11+
12+
# Astro
13+
docs/dist
14+
docs/.astro
15+
16+
# macOS
17+
.DS_Store

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ Automatically sync your project translations with [Loco](https://localise.biz).
1414
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
1515
<br />
1616
<br />
17+
<a href="https://loco-cli.robrecht.me">Documentation</a>
18+
·
1719
<a href="https://github.com/robrechtme/loco-cli/issues">Report Bug</a>
1820
·
1921
<a href="https://github.com/robrechtme/loco-cli/issues">Request Feature</a>

‎docs/astro.config.mjs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
import { defineConfig } from 'astro/config';
2+
import starlight from '@astrojs/starlight';
3+
4+
export default defineConfig({
5+
site: 'https://loco-cli.robrecht.me',
6+
integrations: [
7+
starlight({
8+
title: 'loco-cli',
9+
logo: {
10+
src: './public/logo.svg',
11+
replacesTitle: true
12+
},
13+
customCss: ['./src/styles/custom.css'],
14+
social: {
15+
github: 'https://github.com/robrechtme/loco-cli'
16+
},
17+
sidebar: [
18+
{
19+
label: 'Getting Started',
20+
items: [
21+
{ label: 'Introduction', slug: '' },
22+
{ label: 'Installation', slug: 'installation' },
23+
{ label: 'Configuration', slug: 'configuration' }
24+
]
25+
},
26+
{
27+
label: 'Commands',
28+
items: [
29+
{ label: 'pull', slug: 'commands/pull' },
30+
{ label: 'push', slug: 'commands/push' },
31+
{ label: 'status', slug: 'commands/status' }
32+
]
33+
},
34+
{ label: 'Contributing', slug: 'contributing' }
35+
]
36+
})
37+
]
38+
});

‎docs/package.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"name": "@loco-cli/docs",
3+
"private": true,
4+
"scripts": {
5+
"dev": "astro dev",
6+
"build": "astro build",
7+
"preview": "astro preview"
8+
},
9+
"dependencies": {
10+
"@astrojs/starlight": "^0.32",
11+
"astro": "^5.2",
12+
"sharp": "^0.33"
13+
}
14+
}

‎docs/public/logo.svg‎

Lines changed: 10 additions & 0 deletions
Loading

‎docs/src/content/config.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
import { defineCollection } from 'astro:content';
2+
import { docsSchema } from '@astrojs/starlight/schema';
3+
4+
export const collections = {
5+
docs: defineCollection({ schema: docsSchema() })
6+
};

‎docs/src/content/docs/commands/pull.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: pull
3+
description: Download translations from Loco
4+
---
5+
6+
Download all translations from Loco. This command **overwrites** the JSON files in your `localesDir` with the assets from Loco.
7+
8+
```bash
9+
loco-cli pull
10+
```
11+
12+
## Options
13+
14+
### `-y, --yes`
15+
16+
Automatically answer yes to all confirmation prompts.
17+
18+
```bash
19+
loco-cli pull -y
20+
```
21+
22+
## Pull Options
23+
24+
Additional options can be configured in `loco.config.js` under the `pull` key. See [Configuration](/configuration#pull-options) for details.

‎docs/src/content/docs/commands/push.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: push
3+
description: Upload translations to Loco
4+
---
5+
6+
Push local translation changes to Loco. Depending on your `push` options, this will add new translations, modify existing ones, or delete translations from Loco that aren't in your local files.
7+
8+
```bash
9+
loco-cli push
10+
```
11+
12+
## Options
13+
14+
### `-y, --yes`
15+
16+
Automatically answer yes to all confirmation prompts.
17+
18+
```bash
19+
loco-cli push -y
20+
```
21+
22+
## Push Options
23+
24+
Configure push behavior in `loco.config.js` under the `push` key. See [Configuration](/configuration#push-options) for details.
25+
26+
### Example: Tag new assets
27+
28+
```js
29+
// loco.config.js
30+
module.exports = {
31+
accessKey: '<key>',
32+
localesDir: 'src/locales',
33+
push: {
34+
'flag-new': 'provisional',
35+
'tag-new': 'v1.2.0'
36+
}
37+
};
38+
```

‎docs/src/content/docs/commands/status.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: status
3+
description: Check differences between local and remote translations
4+
---
5+
6+
Check the diff between local and remote translations.
7+
8+
```bash
9+
loco-cli status
10+
```
11+
12+
## Options
13+
14+
### `--direction`
15+
16+
Direction to diff translations:
17+
18+
| Value | Description |
19+
|-------|-------------|
20+
| `remote` | Only check for local translations missing remotely |
21+
| `local` | Only check for remote translations missing locally |
22+
| `both` | Check both directions (default) |
23+
24+
```bash
25+
# Only show what's missing in Loco
26+
loco-cli status --direction remote
27+
28+
# Only show what's missing locally
29+
loco-cli status --direction local
30+
```

‎docs/src/content/docs/configuration.mdx‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Configuration
3+
description: All configuration options for loco-cli
4+
---
5+
6+
Options can be passed as CLI flags or defined in a config file. Config files are loaded via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig):
7+
8+
- `loco.config.js` (recommended)
9+
- `.locorc.yaml`
10+
- `.locorc.json`
11+
- `.locorc.js`
12+
13+
## Example Config
14+
15+
```js
16+
// loco.config.js
17+
/** @type {import('loco-cli/types').Config} */
18+
module.exports = {
19+
accessKey: '<loco-full-access-key>',
20+
localesDir: 'src/app/i18n/locales',
21+
namespaces: false,
22+
push: {
23+
'flag-new': 'provisional',
24+
'tag-new': process.env.npm_package_version,
25+
'delete-absent': false
26+
}
27+
};
28+
```
29+
30+
## Global Options
31+
32+
| Config key | CLI flag | Type | Description |
33+
|------------|----------|------|-------------|
34+
| `accessKey` | `-a`, `--access-key <key>` | `string` | The API key from your Loco project. Find it under **Developer Tools → API Keys → Full Access Key**. An Export key works for pull-only usage. |
35+
| `localesDir` | `-d`, `--locales-dir <path>` | `string` | Folder containing JSON translation files. Defaults to current directory. |
36+
| `namespaces` | `-N`, `--namespaces` | `boolean` | Organize translations into namespaces (default: `false`). When enabled, asset IDs are prefixed with `<namespace>:`. |
37+
| `maxFiles` | `-m`, `--max-files <number>` | `number` | Maximum files to display in diff output (default: `20`). |
38+
| `push` | — | `PushOptions` | Options for `loco-cli push`. See below. |
39+
| `pull` | — | `PullOptions` | Options for `loco-cli pull`. See below. |
40+
41+
## Push Options
42+
43+
Options passed to the [Loco import API](https://localise.biz/api/docs/import/import):
44+
45+
| Option | Description |
46+
|--------|-------------|
47+
| `ignore-new` | New assets will NOT be added to the project |
48+
| `ignore-existing` | Existing assets will NOT be updated |
49+
| `tag-new` | Tag new assets with given tags (comma separated) |
50+
| `tag-all` | Tag ALL assets in the file (comma separated) |
51+
| `untag-all` | Remove tags from matched assets (comma separated) |
52+
| `tag-updated` | Tag assets modified by this import |
53+
| `untag-updated` | Remove tags from modified assets |
54+
| `tag-absent` | Tag assets NOT found in the imported file |
55+
| `untag-absent` | Remove tags from assets NOT in the file |
56+
| `delete-absent` | **Permanently delete** assets NOT in the file (use with caution) |
57+
| `flag-new` | Set flag on new non-empty translations |
58+
59+
## Pull Options
60+
61+
Options passed to the [Loco export API](https://localise.biz/api/docs/export/exportall):
62+
63+
| Option | Description |
64+
|--------|-------------|
65+
| `filter` | Filter by tags. Match any with `*`, negate with `!` prefix |
66+
| `fallback` | Fallback locale for untranslated assets (e.g., `en` or `en_GB`) |
67+
| `order` | Export according to asset order |
68+
| `status` | Export by status/flag. Negate with `!` (e.g., `translated`, `!fuzzy`) |
69+
| `charset` | Preferred character encoding |
70+
| `breaks` | Force platform-specific line endings (default: Unix LF) |

0 commit comments

Comments
 (0)