diff --git a/.puprc-defaults b/.puprc-defaults index 652f4a6..66dee83 100644 --- a/.puprc-defaults +++ b/.puprc-defaults @@ -26,9 +26,7 @@ "file_format": "%textdomain%-%wp_locale%.%format%", "formats": ["po", "mo"], "filter": { - "translation_sets": false, - "minimum_percentage": 30, - "waiting_strings": false + "minimum_percentage": 30 } }, "paths": { diff --git a/README.md b/README.md index 525c50a..03485c7 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ This is a CLI utility built by [StellarWP](https://stellarwp.com) for running pr * [Install globally as a git clone](/docs/installation.md#install-globally-as-a-git-clone) - another good option for your system. * [Configuration](/docs/configuration.md) * [Glob patterns](/docs/glob-patterns.md) - for your `.distfiles` and `.distignore` files. + * [Internationalization (i18n)](/docs/i18n.md) * [Commands](/docs/commands.md) * [`pup build`](/docs/commands.md#pup-build) * [`pup check`](/docs/commands.md#pup-check) diff --git a/docs/commands.md b/docs/commands.md index c2bffa9..e49f5a2 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -86,8 +86,8 @@ composer -- pup check:tbd | `fail_method` | **Optional.** How the check should fail. Defaults to `error`. | | `fail_method_dev` | **Optional.** How the check should fail when running with `--dev`. Defaults to `warn`. | | `dirs` | **Optional.** An array of directories to scan. Defaults to `['src']`. | -| `skip_directories` | **Optional.** A pipe delimited list of directories to skip. Defaults can be seen in [`.puprc-defaults`](/.puprc-defaults). | -| `skip_files` | **Optional.** A pipe delimited list of files to skip. Defaults can be seen in [`.puprc-defaults`](/.puprc-defaults). | +| `skip_directories` | **Optional.** A pipe delimited list of directories to skip. Defaults can be seen in [`.puprc-defaults`](https://github.com/stellarwp/pup/blob/main/.puprc-defaults). | +| `skip_files` | **Optional.** A pipe delimited list of files to skip. Defaults can be seen in [`.puprc-defaults`](https://github.com/stellarwp/pup/blob/main/.puprc-defaults). | ### `pup check:version-conflict` @@ -131,7 +131,7 @@ composer -- pup clean ## `pup get-version` Gets your project's version number. -This command will use the first [version file](/docs/configuration.md#paths-versions) declared in your `.puprc` file to get the version number. +This command will use the first [version file](https://github.com/stellarwp/pup/blob/main/docs/configuration.md#paths-versions) declared in your `.puprc` file to get the version number. If you haven't provided a version file, the version will be `unknown`. ### Usage @@ -190,27 +190,10 @@ a bare minimum, you must specify the following: } ``` -If you wish to specify multiple `i18n` configs, being sure to override the `path` value so that the second config -will download language files to an alternate location: - -```json -"i18n": [ - { - "slug": "the-slug-used-in-glotpress", - "textdomain": "my-textdomain", - "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable" - }, - { - "path": "some-other-path/lang", - "slug": "the-slug-used-in-glotpress", - "textdomain": "my-textdomain", - "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable" - } -] -``` - By default, the config settings for `i18n` inherit defaults from the `i18n_defaults` values in the -[`.puprc-defaults`](/.puprc-defaults) found within `pup`. +[`.puprc-defaults`](https://github.com/stellarwp/pup/blob/main/.puprc-defaults) found within `pup`. + +For more information on the available options, see the [i18n documentation](https://github.com/stellarwp/pup/blob/main/docs/i18n.md). ## `pup info` Gets `pup` details for the current project. @@ -270,7 +253,7 @@ composer -- pup package [--dev] ## `pup zip` Runs the full `pup` set of commands to create a zip file. -This command is a wrapper command for the whole zipping process. You can see its [flow of commands](/docs/flow.md) for +This command is a wrapper command for the whole zipping process. You can see its [flow of commands](https://github.com/stellarwp/pup/blob/main/docs/flow.md) for more information on which commands it runs and when. ### Usage diff --git a/docs/i18n.md b/docs/i18n.md new file mode 100644 index 0000000..1f25052 --- /dev/null +++ b/docs/i18n.md @@ -0,0 +1,55 @@ +# Internationalization (i18n) + +The `pup i18n` command can be used do fetch language files from a GlotPress instance for your project. To enable this +command, you must configure the `i18n` section of your `.puprc` file. + +## The bare minimum + +```json +{ + "i18n": { + "slug": "the-slug-used-in-glotpress", + "textdomain": "my-textdomain", + "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable" + } +} +``` + +By default, the config settings for `i18n` inherit defaults from the `i18n_defaults` values in the +[`.puprc-defaults`](/.puprc-defaults) found within `pup`. + +## Fetching from multiple sources + +If you wish to specify multiple `i18n` configs, being sure to override the `path` value so that the second config +will download language files to an alternate location: + +```json +{ + "i18n": [ + { + "slug": "the-slug-used-in-glotpress", + "textdomain": "my-textdomain", + "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable" + }, + { + "path": "some-other-path/lang", + "slug": "the-slug-used-in-glotpress", + "textdomain": "my-textdomain", + "url": "https://translate.wordpress.org/api/projects/wp-plugins/{slug}/stable" + } + ] +} +``` + +## All options + +| Config option | Type | Description | +|-----------------------------|---|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `file_format` | `string` | The format of the file name for each language file that is downloaded. See [`.puprc-defaults`](/.puprc-defaults) for the default value. | +| `filter` | `object` | This is the containing object for filters used in fetching language files. | +| `filter.minimum_percentage` | `boolean` | The percentage of strings that must be translated in order to download the file. See [`.puprc-defaults`](/.puprc-defaults) for the default value. | +| `formats` | `array` | The array of file formats to download. Defaults to `['mo', 'po']`. | +| `path` | `string` | The path to download the language files to. Defaults to `lang`. | +| `slug` | `string` | The slug used in GlotPress to identify the project. | +| `textdomain` | `string` | The textdomain used in the project. | +| `url` | `string` | The URL to the GlotPress API endpoint. |