forked from Mirrors/elk
docs: add contributing guide (#697)
This commit is contained in:
Joaquín Sánchez
GitHub
parent
5e3156a638
commit
c2261370b4
2 changed files with 113 additions and 1 deletions
112
CONTRIBUTING.md
Normal file
112
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
# Contributing Guide
|
||||
|
||||
Hi! We are really excited that you are interested in contributing to Elk. Before submitting your contribution, please make sure to take a moment and read through the following guide.
|
||||
|
||||
Refer also to https://github.com/antfu/contribute.
|
||||
|
||||
## Set up your local development environment
|
||||
|
||||
The package manager used to install and link dependencies must be [pnpm](https://pnpm.io/).
|
||||
|
||||
To develop and test the Elk package:
|
||||
|
||||
1. Fork the Elk repository to your own GitHub account and then clone it to your local device.
|
||||
|
||||
2. Ensure using the latest Node.js (16.x)
|
||||
|
||||
3. Elk uses pnpm v7, you must enable [Corepack](https://github.com/nodejs/corepack) by running `corepack enable`.
|
||||
|
||||
4. Check out a branch where you can work and commit your changes:
|
||||
```shell
|
||||
git checkout -b my-new-branch
|
||||
```
|
||||
|
||||
5. Run `pnpm i` in Elk's root folder
|
||||
|
||||
6. Run `pnpm nuxi prepare` in Elk's root folder
|
||||
|
||||
7. Run `pnpm dev` in Elk's root folder to start dev server or `pnpm dev:mocked` to start dev server with `@elkdev@universeodon.com` user.
|
||||
|
||||
## Internalization
|
||||
|
||||
We are using [vue-i18n](https://vue-i18n.intlify.dev/) via [nuxt-i18n](https://i18n.nuxtjs.org/) to handle internalization.
|
||||
|
||||
### Adding a new language
|
||||
|
||||
1. Add a new file in [locales](../locales) folder with the language code as the filename.
|
||||
2. Copy [en-US](../locales/en-US.json) and translate the strings.
|
||||
3. Add the language to the `locales` array in [config/i18n.ts](../config/i18n.ts#L13)
|
||||
4. If the language is `right-to-left`, add `dir` option with `rtl` value, for example, for [ar-EG](../config/i18n.ts#L63)
|
||||
5. If the language requires special pluralization rules, add `pluralRule` callback option, for example, for [ar-EG](../config/i18n.ts#L64)
|
||||
|
||||
Check [Pluralization rule callback](https://vue-i18n.intlify.dev/guide/essentials/pluralization.html#custom-pluralization) for more info.
|
||||
|
||||
### Messages interpolation
|
||||
|
||||
Most of the messages used in Elk do not require any interpolation, however, there are some messages that require interpolation: check [Message Format Syntax](https://vue-i18n.intlify.dev/guide/essentials/syntax.html) for more info.
|
||||
|
||||
We're using these types of interpolation:
|
||||
- [List interpolation](https://vue-i18n.intlify.dev/guide/essentials/syntax.html#list-interpolation)
|
||||
- [Named interpolation](https://vue-i18n.intlify.dev/guide/essentials/syntax.html#interpolations)
|
||||
- [Linked messages](https://vue-i18n.intlify.dev/guide/essentials/syntax.html#linked-messages)
|
||||
- [Literal interpolation](https://vue-i18n.intlify.dev/guide/essentials/syntax.html#literal-interpolation)
|
||||
|
||||
#### List interpolation
|
||||
|
||||
You can access the elements of the list using the object notation using the index: for example, `{0}` for the first element, `{1}` for the second, `{2}` for the third and so on.
|
||||
|
||||
#### Named interpolation
|
||||
|
||||
Elk will use named interpolation only to handle plurals for number formatting. We have 2 scenarios for this:
|
||||
- using `plural` **with** `i18n-t` component
|
||||
- using `plural` **without** `i18n-t` component
|
||||
|
||||
Check [Custom Plural Number Formatting Entries](#custom-plural-number-formatting-entries) for custom plural entries in Elk with available values for interpolation.
|
||||
|
||||
When using plural number formatting, we'll have always `{n}` available in the message, for example, `You have {n} new notifications|You have {n} new notification|You have {n} new notifications` or `You have no new notifications|You have 1 new notification|You have {n} new notifications`.
|
||||
|
||||
We've included `v` named parameter, it will be used to pass the formatted number using [Intl.NumberFormat::format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/format): will be the number with separators symbols. The exception to previous rule is when we're using `plural` **with** `i18n-t` component, in this case, we'll need to use `{0}` instead `{v}` to access the number.
|
||||
|
||||
Additionally, Elk will use [compact notation for numbers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#parameters) for some entries, check `notation` and `compactDisplay` options: for example, `1K` for `1000`, `1M` for `1000000`, `1B` for `1000000000` and so on. That entry will be available in the message using `{v}` named parameter (or `{0}` if using the message **with** `i18n-t` component).
|
||||
|
||||
You can run this code in your browser console to see how it works:
|
||||
```ts
|
||||
[1, 12, 123, 1234, 12345, 123456, 1234567].forEach((n) => {
|
||||
const acc = {}
|
||||
|
||||
Array.from(['en-US', 'en-GB', 'de-DE', 'zh-CN', 'ja-JP', 'es-ES', 'fr-FR', 'cs-CZ', 'ar-EG']).forEach((l) => {
|
||||
const nf = new Intl.NumberFormat(l, {
|
||||
style: 'decimal',
|
||||
maximumFractionDigits: 0,
|
||||
})
|
||||
const nf2 = new Intl.NumberFormat(l, {
|
||||
notation: 'compact',
|
||||
compactDisplay: 'short',
|
||||
maximumFractionDigits: 1,
|
||||
})
|
||||
acc[l] = {
|
||||
number: n,
|
||||
format: nf.format(n),
|
||||
compact: nf2.format(n),
|
||||
}
|
||||
})
|
||||
console.table(acc)
|
||||
})
|
||||
```
|
||||
|
||||
#### Custom Plural Number Formatting Entries
|
||||
|
||||
**Warning**:
|
||||
**{0} should be use** or **{v} should be use** or **{followers} should be use**: with the exception of custom plural entries where the number (`{n}`) is required.
|
||||
Either **{0}**, **{v}** or **{followers}** should be used with the exception being custom plurals entries using the `{n}` placeholder.
|
||||
This is the full list of entries that will be available for number formatting in Elk:
|
||||
- `action.boost_count` (no need to be included, we should use always `en-US` entry): `{0}` for formatted number and `{n}` for raw number - **{0} should be use**
|
||||
- `action.favourite_count` (no need to be included, we should use always `en-US` entry): `{0}` for formatted number and `{n}` for raw number - **{0} should be use**
|
||||
- `action.reply_count` (no need to be included, we should use always `en-US` entry): `{0}` for formatted number and `{n}` for raw number - **{0} should be use**
|
||||
- `account.followers_count`: `{0}` for formatted number and `{n}` for raw number - **{0} should be use**
|
||||
- `account.following_count`: `{0}` for formatted number and `{n}` for raw number - **{0} should be use**
|
||||
- `account.posts_count`: `{0}` for formatted number and `{n}` for raw number - **{0} should be use**
|
||||
- `notification.followed_you_count`: `{followers}` for formatted number and `{n}` for raw number - **{followers} should be use**
|
||||
- `status.poll.count`: `{0}` for formatted number and `{n}` for raw number - **{0} should be use**
|
||||
- `time_ago_options.*`: `{0}` for formatted number and `{n}` for raw number - **{0} should be use**: since numbers will be always small, we can also use `{n}`
|
||||
- `timeline.show_new_items`: `{v}` for formatted number and `{n}` for raw number - **{v} should be use**
|
||||
|
|
@ -69,4 +69,4 @@ nr test
|
|||
|
||||
# License
|
||||
|
||||
MIT
|
||||
[MIT](./LICENSE) © 2022-PRESENT Elk contributors
|
||||
|
|
|
|||
Loading…
Reference in a new issue