From c2261370b41012ae4f1389e1e92d5eace85366cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joaqu=C3=ADn=20S=C3=A1nchez?= Date: Mon, 2 Jan 2023 14:48:17 +0100 Subject: [PATCH] docs: add contributing guide (#697) --- CONTRIBUTING.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 2 files changed, 113 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..584ba380 --- /dev/null +++ b/CONTRIBUTING.md @@ -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** diff --git a/README.md b/README.md index 9339a913..f859bcbd 100644 --- a/README.md +++ b/README.md @@ -69,4 +69,4 @@ nr test # License -MIT +[MIT](./LICENSE) © 2022-PRESENT Elk contributors