mirror of
https://github.com/Lissy93/dashy.git
synced 2024-11-22 20:25:13 +03:00
📝 Updates maintence and language docs
This commit is contained in:
Alicia Sykes
parent
4888f2a803
commit
1311ceda92
@ -37,25 +37,28 @@ Dashy should now be being served on http://localhost:8080/. Hot reload is enable
|
||||
|
||||
### Project Commands
|
||||
|
||||
- `yarn dev` - Starts the development server with hot reloading
|
||||
- `yarn build` - Builds the project for production, and outputs it into `./dist`
|
||||
- `yarn start` - Starts a web server, and serves up the production site from `./dist`
|
||||
- `yarn validate-config` - Parses and validates your `conf.yml` against Dashy's schema
|
||||
- `yarn lint` - Lints code to ensure it follows a consistent, neat style
|
||||
- `yarn test` - Runs tests, and outputs results
|
||||
#### Basics
|
||||
- **`yarn build`** - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run `yarn build` or `docker exec -it [container-id] yarn build`
|
||||
- **`yarn start`** - Starts a web server, and serves up the production site from `./dist` (must run build command first)
|
||||
|
||||
There is also:
|
||||
- `yarn build-and-start` will run `yarn build` and `yarn start`
|
||||
- `yarn build-watch` will output contents to `./dist` and recompile when anything in `./src` is modified, you can then use either `yarn start` or your own server, to have a production environment that watches for changes.
|
||||
#### Development
|
||||
- **`yarn dev`** - Starts the development server with hot reloading
|
||||
- **`yarn lint`** - Lints code to ensure it follows a consistent, neat style
|
||||
- **`yarn test`** - Runs tests, and outputs results
|
||||
|
||||
Using the Vue CLI:
|
||||
- The app is build with Vue, and uses the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html) for basic commands.
|
||||
- If you have [NPX](https://github.com/npm/npx) installed, then you can invoke the Vue CLI binary using `npx vue-cli-service [command]`
|
||||
- Vue also has a GUI environment that can be used for basic project management, and may be useful for beginners, this can be started by running `npx vue ui`, and opening up `http://localhost:8000`
|
||||
#### Utils and Checks
|
||||
- **`yarn validate-config`** - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with `yarn validate-config` or `docker exec -it [container-id] yarn validate-config`. Your config file needs to be in `/public/conf.yml` (or within your Docker container at `/app/public/conf.yml`). This will first check that your YAML is valid, and then validates it against Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js).
|
||||
- **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability
|
||||
|
||||
Note:
|
||||
#### Alternate Start Commands
|
||||
- **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the `yarn build` and `yarn start` commands
|
||||
- **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
|
||||
- **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command
|
||||
|
||||
#### Notes
|
||||
- If you are using NPM, replace `yarn` with `npm run`
|
||||
- If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps`
|
||||
- You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000`
|
||||
|
||||
### Environmental Variables
|
||||
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
|
||||
|
||||
@ -3,22 +3,18 @@
|
||||
## Providing Assets
|
||||
Although not essential, you will most likely want to provide several assets to Dashy. All web assets can be found in the `/public` directory.
|
||||
|
||||
For example:
|
||||
- `./public/conf.yml` - As mentioned, this is your main application config file
|
||||
- `./public/item-icons` - If you're using your own icons, you can choose to store them locally for better load time, and this is the directory to put them in. You can also use sub-folders here to keep things organized. You then reference these assets relative this the direcroties path, for example: to use `./public/item-icons/networking/netdata.png` as an icon for one of your links, you would set `icon: networking/netdata.png`
|
||||
- Also within `./public` you'll find standard website assets, including `favicon.ico`, `manifest.json`, `robots.txt`, etc. There's no need to modify these, but you can do so if you wish.
|
||||
- `./public/item-icons` - If you're using your own icons, you can choose to store them locally for better load time, and this is the directory to put them in. You can also use sub-folders here to keep things organized
|
||||
- Also within `./public` you'll find standard website assets, including `favicon.ico`, `manifest.json`, `robots.txt`, etc. There's no need to pass these in, but you can do so if you wish
|
||||
|
||||
## Basic Commands
|
||||
This is easy to do using [Docker Volumes](https://docs.docker.com/storage/volumes/), which lets you share a file or directory between your host system, and the container. Volumes are specified in the Docker run command, or Docker compose file, using the `--volume` or `-v` flags. The value of which consists of the path to the file / directory on your host system, followed by the destination path within the container. Fields are separated by a colon (`:`), and must be in the correct order. For example: `-v ~/alicia/my-local-conf.yml:/app/public/conf.yml`
|
||||
|
||||
Now that you've got Dashy running, there are a few commands that you need to know.
|
||||
## Running Commands
|
||||
|
||||
The following commands are defined in the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5) file, and are run with `yarn`. If you prefer, you can use NPM, just replace instances of `yarn` with `npm run`. If you are using Docker, then you will need to precede each command with `docker exec -it [container-id]`, where container ID can be found by running `docker ps`. For example `docker exec -it 26c156c467b4 yarn build`.
|
||||
The project has a few commands that can be used for various tasks, you can find a list of these either in the [Developing Docs](/docs/developing.md#project-commands), or by looking at the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5). These can be used by running `yarn [command-name]`.
|
||||
|
||||
- **`yarn build`** - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run `yarn build` or `docker exec -it [container-id] yarn build`
|
||||
- **`yarn validate-config`** - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with `yarn validate-config` or `docker exec -it [container-id] yarn validate-config`. Your config file needs to be in `/public/conf.yml` (or within your Docker container at `/app/public/conf.yml`). This will first check that your YAML is valid, and then validates it against Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js).
|
||||
- **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability
|
||||
- **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
|
||||
- **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently
|
||||
- **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command
|
||||
But if you're using Docker, then you'll need to execute them within the container. This can be done by preceding each command with `docker exec -it [container-id]`, where container ID can be found by running `docker ps`. For example `docker exec -it 26c156c467b4 yarn build`. You can also enter the container, with `docker exec -it [container-id] /bin/ash`, and navigate around it with normal Linux commands.
|
||||
|
||||
## Healthchecks
|
||||
|
||||
|
||||
@ -1,23 +1,32 @@
|
||||
# Internationalization
|
||||
|
||||
Internationalization is the process of making an application available in other languages. This is important, as not everyone is a native English speaker.
|
||||
Internationalization is the process of making an application available in other languages. This is important, as not everyone is a native English speaker. This page explains how you can switch languages, how to add a new language, and how to make text translatable when writing a new component.
|
||||
|
||||
## Available Languages
|
||||
|
||||
An up-to-date list of all currently supported languages can be found in [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/languages.js). Languages are specified by their 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`, `fr`, `de`, `es`, etc)
|
||||
- [Setting your Language](#setting-language)
|
||||
- [Adding a new Language](#adding-a-new-language)
|
||||
- [Adding New Text to a Component](#adding-new-text-to-a-component)
|
||||
|
||||
---
|
||||
|
||||
## How to change Language
|
||||
## Setting Language
|
||||
|
||||
By default, Dashy will attempt to use the language of your browser or system. If a translation for your language does not yet exist, it will fallback to English.
|
||||
|
||||
You can also manually select your language. This can be done, either through the UI (Config --> Language), or by setting it in your config file:
|
||||
#### In the UI
|
||||
You can manually select your language in the UI. Under the Config Menu, click the Language button, and select your language from the dropdown menu. Your preference will be saved in local storage.
|
||||
|
||||
#### Config File
|
||||
You can also set your language in the config file. Specify the ISO code of one of the supported languages, under `appConfig.lang`. For example:
|
||||
|
||||
```yaml
|
||||
appConfig:
|
||||
lang: de
|
||||
lang: de
|
||||
```
|
||||
|
||||
#### Available Languages
|
||||
|
||||
At the time of writing the following languages are supported: `en`, `zh-CN`, `nl`, `fr`, `de`, `es`, `sl`, `it`, `pt`, `ru`, `ar`, `hi`, `ja`, but an up-to-date list of all implemented translations can be found in [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/languages.js). Languages are specified by their 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), or sometimes a 4-digit code if it's a regional dialect.
|
||||
|
||||
---
|
||||
|
||||
## Adding a new Language
|
||||
@ -27,9 +36,10 @@ Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-l
|
||||
Adding a new language is pretty straightforward, with just three steps:
|
||||
|
||||
##### 1. Create a new Language File
|
||||
Create a new JSON file in `./src/assets/locales` name is a 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, E.g. for German `de.json`, French `fr.json` or Spanish `es.json` - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).
|
||||
If your language is a specific dialect or regional language, then use the Posfix [CLDR](http://cldr.unicode.org/) format, where, e.g. `en-GB.json` (British), `es-MX.json` (Spanish, in Mexico) or `zh-CN.json` (Chinese, simplified) - A list of which can be found [here](https://github.com/unicode-org/cldr-json/blob/master/cldr-json/cldr-core/availableLocales.json)
|
||||
Create a new JSON file in `./src/assets/locales` for your language.
|
||||
|
||||
You should name it with the 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your locale (e.g. for German `de.json`, French `fr.json` or Spanish `es.json`) - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).
|
||||
If your language is a specific dialect or regional translation, then use the Posfix [CLDR](http://cldr.unicode.org/) format, where, e.g. `en-GB.json` (British English), `es-MX.json` (Spanish, in Mexico) or `zh-CN.json` (Chinese, simplified) - A list of which can be found [here](https://github.com/unicode-org/cldr-json/blob/master/cldr-json/cldr-core/availableLocales.json)
|
||||
|
||||
##### 2. Translate!
|
||||
Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locales/en.json) as an example, translate the JSON values to your language, while leaving the keys as they are. It's fine to leave out certain items, as if they're missing they will fall-back to English. If you see any attribute which include curly braces (`{xxx}`), then leave the inner value of these braces as is, as this is for variables.
|
||||
@ -78,12 +88,9 @@ If you are not comfortable with making pull requests, or do not want to modify t
|
||||
|
||||
---
|
||||
|
||||
## Adding Text
|
||||
|
||||
If you're working on a new component, then any text that is displayed to the user should be extracted out of the component, and stored in the file. This also applies to any existing components, that might have been forgotten to be translated.
|
||||
|
||||
Thankfully, everything is already setup, and so is as easy as adding text to the JSON file, and pasting the key to that text in your component.
|
||||
## Adding New Text to a Component
|
||||
|
||||
If you're working on a new component, then any text that is displayed to the user should be extracted out of the component, and stored in the file. This also applies to any existing components, that might have been forgotten to be translated. Thankfully, everything is already setup, so this is a pretty easy job.
|
||||
|
||||
#### 1. Add Translated Text
|
||||
|
||||
@ -95,8 +102,7 @@ Firstly, go to [`./src/assets/locales/en.json`](https://github.com/Lissy93/dashy
|
||||
}
|
||||
```
|
||||
|
||||
Note that you **must** add English translations for all text. Missing languages are not a problem, as they will always fallback to Enslish, but if the English is missing, then nothing can be displayed.
|
||||
|
||||
Note that you **must** add English translations for all text. Missing languages are not a problem, as they will always fallback to English, but if the English is missing, then nothing can be displayed.
|
||||
|
||||
#### 2. Use Text within Component
|
||||
|
||||
@ -143,10 +149,9 @@ In [`./src/components/Settings/SearchBar.vue`](https://github.com/Lissy93/dashy/
|
||||
<form>
|
||||
<label for="search-input">{{ $t('search.search-label') }}</label>
|
||||
<input
|
||||
id="search-input"
|
||||
v-model="searchValue"
|
||||
:placeholder="$t('search.search-placeholder')"
|
||||
/>
|
||||
/>
|
||||
</form>
|
||||
</template>
|
||||
```
|
||||
@ -159,6 +164,6 @@ Then in [`./src/assets/locales/en.json`](https://github.com/Lissy93/dashy/blob/m
|
||||
"search-label": "Search",
|
||||
"search-placeholder": "Start typing to filter",
|
||||
},
|
||||
...
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user