Merge pull request #28 from 343dev/imporvement/docs

Update README

Author: 343dev

README.md

@@ -1,16 +1,14 @@
 # @343dev/optimizt
 
 <img align="right" width="192" height="192"
-     alt="Optimizt avatar: OK sign with Mona Lisa picture between the fingers"
+     alt="Optimizt logo: OK hand sign with Mona Lisa image between the fingers"
      src="./docs/logo.png">
 
 [![npm](https://img.shields.io/npm/v/@343dev/optimizt.svg)](https://www.npmjs.com/package/@343dev/optimizt)
 
 **Optimizt** is a command-line tool that helps prepare images for the web.
 
-It can compress PNG, JPEG, GIF and SVG lossy and lossless, and also create AVIF and WebP versions for raster images.
-
-[По-русски](./README.ru.md)
+It can compress PNG, JPEG, GIF, and SVG lossy or lossless, and create AVIF and WebP versions for raster images.
 
 ## Rationale
 
@@ -21,7 +19,7 @@ As frontend developers, we have to care about pictures: compress PNG and JPEG, r
 Install:
 
 ```sh
-npm i -g @343dev/optimizt
+npm install -g @343dev/optimizt
 ```
 
 Optimize!
@@ -30,123 +28,110 @@ Optimize!
 optimizt path/to/picture.jpg
 ```
 
-## Command line flags
+## Command Line Flags
 
 - `--avif` — create AVIF versions of images.
 - `--webp` — create WebP versions of images.
-- `-f, --force` — recreate AVIF and WebP versions if the file already exists.
+- `-f, --force` — recreate AVIF and WebP versions even if they already exist.
 - `-l, --lossless` — optimize losslessly instead of lossily.
-- `-v, --verbose` — show more details during the process (e.g. skipped files).
-- `-c, --config` — use a provided configuration file instead of the default one.
-- `-o, --output` — write result to provided directory.
-- `-V, --version` — show the tool version.
-- `-h, --help` — show help.
+- `-v, --verbose` — show detailed output (e.g. skipped files).
+- `-c, --config` — use a custom configuration file instead of the default.
+- `-o, --output` — write results to the specified directory.
+- `-V, --version` — display the tool version.
+- `-h, --help` — show help message.
 
 ## Usage Examples
 
 ```bash
-# optimize one image
+# optimize a single image
 optimizt path/to/picture.jpg
 
-# optimize several images losslessly
+# optimize multiple images losslessly
 optimizt --lossless path/to/picture.jpg path/to/another/picture.png
 
-# recursively create AVIF and WebP versions for images in a directory
+# recursively create AVIF and WebP versions for all images in a directory
 optimizt --avif --webp path/to/directory
 
 # recursively optimize JPEG files in the current directory
 find . -iname \*.jpg -exec optimizt {} +
 ```
 
-## Differences between Lossy and Lossless
-
-### Lossy (default)
+## Differences Between Lossy and Lossless
 
-Gives the best balance between compression and minimal visual changes.
+### Lossy (Default)
 
-### Lossless (with `--lossless` flag)
+Provides the best balance between file size reduction and minimal visual quality loss.
 
-When creating AVIF and WebP, it uses lossless compression. For PNG, JPEG, and GIF optimization, it maximizes image quality at the cost of larger file size.
+### Lossless (`--lossless` flag)
 
-For SVG files, the settings in Lossy and Lossless modes are identical.
+- **AVIF/WebP**: Uses lossless compression.
+- **PNG/JPEG/GIF**: Maximizes image quality at the expense of larger file sizes.
+- **SVG**: Settings are identical in both modes.
 
 ## Configuration
 
-Image processing is done using [sharp](https://github.com/lovell/sharp) for [JPEG](https://sharp.pixelplumbing.com/api-output#jpeg), [PNG](https://sharp.pixelplumbing.com/api-output#png), [WebP](https://sharp.pixelplumbing.com/api-output#webp), and [AVIF](https://sharp.pixelplumbing.com/api-output#avif).
+Image processing leverages:
 
-SVG is processed by [svgo](https://github.com/svg/svgo), while for GIF, [gifsicle](https://github.com/kohler/gifsicle) is used.
+- [sharp](https://github.com/lovell/sharp) for [JPEG](https://sharp.pixelplumbing.com/api-output#jpeg), [PNG](https://sharp.pixelplumbing.com/api-output#png), [WebP](https://sharp.pixelplumbing.com/api-output#webp), and [AVIF](https://sharp.pixelplumbing.com/api-output#avif).
+- [svgo](https://github.com/svg/svgo) for SVG.
+- [gifsicle](https://github.com/kohler/gifsicle) for GIF.
 
 > [!NOTE]
-> In Lossless mode for JPEG, we use [Guetzli](https://github.com/google/guetzli), which offers high level of compression with good visual quality. However, repeated optimization may degrade visual quality.
-
-The default settings are located in [.optimiztrc.cjs](./.optimiztrc.cjs), and the file contains a list of supported parameters and their brief description.
-
-To disable any parameter, use the value `false`.
+> In Lossless mode for JPEG, [Guetzli](https://github.com/google/guetzli) is used. Repeated optimization may degrade visual quality.
 
-When running with the `--config path/to/.optimiztrc.cjs` flag, the settings from the specified configuration file will be used for image processing.
+Default settings are defined in [.optimiztrc.cjs](./.optimiztrc.cjs), which includes all supported parameters. Disable any parameter by setting it to `false`.
 
-If no `--config` flag is provided, a recursive search for the `.optimiztrc.cjs` file will be performed, starting from the current directory up to the root of the file system. If the file is not found, the default settings will be applied.
+When using `--config path/to/.optimiztrc.cjs`, the specified configuration file will be used. If no `--config` is provided, Optimizt searches recursively from the current directory upward for `.optimiztrc.cjs`. If none is found, defaults are applied.
 
 ## Troubleshooting
 
-### “spawn guetzli ENOENT”, etc.
-
-Make sure that the [ignore-scripts](https://docs.npmjs.com/cli/v6/using-npm/config#ignore-scripts) option is not enabled.
+### Errors like “spawn guetzli ENOENT”.
 
+Ensure the [ignore-scripts](https://docs.npmjs.com/cli/v6/using-npm/config#ignore-scripts) npm option is disabled.
 Details: [funbox/optimizt/issues/9](https://github.com/funbox/optimizt/issues/9).
 
-### “pkg-config: command not found”, “fatal error: 'png.h' file not found”, etc.
-
-Some OS may lack necessary libraries. Install them manually.
-
-Example for macOS using [Homebrew](https://brew.sh):
-
-```bash
-brew install pkg-config libpng
-```
-
 ## Docker
 
-### Using a pre-built image
+### Pre-Built Image
 
 ```bash
-# pull by name
+# pull latest
 docker pull 343dev/optimizt
 
-# pull by name and version
+# pull specific version
 docker pull 343dev/optimizt:9.0.2
 ```
 
-### Build the image manually
+### Manual Build
 
 ```bash
-# clone the Optimizt repository
+# clone repository
 git clone https://github.com/343dev/optimizt.git
-
-# go to the repository folder
 cd optimizt
 
-# build the image
+# build image
 docker build --tag 343dev/optimizt .
 ```
 
-OR:
+Alternatively:
 
 ```bash
-# build the image without cloning the repository
-# in this case “.dockerignore” file will be ignored; see: https://github.com/docker/cli/issues/2827
+# build directly from GitHub
+# ignores .dockerignore (see: https://github.com/docker/cli/issues/2827)
 docker build --tag 343dev/optimizt https://github.com/343dev/optimizt.git
 ```
 
-### Running the container
+### Run Container
 
 ```bash
-# inside the container, WORKDIR is set to `/src`, so all paths will resolve from there
+# mount current directory to /src in the container
 docker run --rm --volume $(pwd):/src 343dev/optimizt --webp ./image.png
 ```
 
 ## Integrations
 
+Optimizt works seamlessly with:
+
 - [JetBrains IDEs](./docs/jetbrains.md)
 - [Visual Studio Code](./docs/vscode.md)
 - [Sublime Text 3](./docs/sublime-text.md)

README.ru.md

@@ -19,11 +19,11 @@
 	"author": "Andrey Warkentin (https://github.com/343dev)",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/343dev/optimizt"
+		"url": "git+https://github.com/343dev/optimizt.git"
 	},
 	"exports": "./index.js",
 	"bin": {
-		"optimizt": "./cli.js"
+		"optimizt": "cli.js"
 	},
 	"files": [
 		"MIGRATION.md",