@juit/vue-i18n 0.0.0

package/LICENSE.md

@@ -0,0 +1,211 @@
+# Apache License
+
+Version 2.0, January 2004
+
+[http://www.apache.org/licenses/](http://www.apache.org/licenses/)
+
+##### TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+### 1. Definitions.
+
+"**License**" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"**Licensor**" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"**Legal Entity**" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"**control**" means **(i)** the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, _or_ **(ii)** ownership of fifty percent (50%) or more of
+the outstanding shares, _or_ **(iii)** beneficial ownership of such
+entity.
+
+"**You**" (or "**Your**") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"**Source**" form shall mean the preferred form for making
+modifications, including but not limited to software source code,
+documentation source, and configuration files.
+
+"**Object**" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but not
+limited to compiled object code, generated documentation, and
+conversions to other media types.
+
+"**Work**" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work (an example
+is provided in the Appendix below).
+
+"**Derivative Works**" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"**Contribution**" shall mean any work of authorship, including the
+original version of the Work and any modifications or additions to that
+Work or Derivative Works thereof, that is intentionally submitted to
+Licensor for inclusion in the Work by the copyright owner or by an
+individual or Legal Entity authorized to submit on behalf of the
+copyright owner. For the purposes of this definition, "**submitted**"
+means any form of electronic, verbal, or written communication sent to
+the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "**Not a
+Contribution**".
+
+"**Contributor**" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+### 2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor
+hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+royalty-free, irrevocable copyright license to reproduce, prepare
+Derivative Works of, publicly display, publicly perform, sublicense,
+and distribute the Work and such Derivative Works in Source or Object
+form.
+
+### 3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor
+hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and
+otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily
+infringed by their Contribution(s) alone or by combination of their
+Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+the Work or a Contribution incorporated within the Work constitutes
+direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+### 4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works
+thereof in any medium, with or without modifications, and in Source or
+Object form, provided that You meet the following conditions:
+
+<ol type="a">
+  <li>You must give any other recipients of the Work or Derivative Works
+    a copy of this License; and
+  <li>You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+  <li>You must retain, in the Source form of any Derivative Works that
+    You distribute, all copyright, patent, trademark, and attribution
+    notices from the Source form of the Work, excluding those notices
+    that do not pertain to any part of the Derivative Works; and
+  <li>If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained within
+    such NOTICE file, excluding those notices that do not pertain to any
+    part of the Derivative Works, in at least one of the following
+    places: within a NOTICE text file distributed as part of the
+    Derivative Works; within the Source form or documentation, if
+    provided along with the Derivative Works; or, within a display
+    generated by the Derivative Works, if and wherever such third-party
+    notices normally appear. The contents of the NOTICE file are for
+    informational purposes only and do not modify the License. You may
+    add Your own attribution notices within Derivative Works that You
+    distribute, alongside or as an addendum to the NOTICE text from the
+    Work, provided that such additional attribution notices cannot be
+    construed as modifying the License.
+</ol>
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated
+in this License.
+
+### 5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally
+submitted for inclusion in the Work by You to the Licensor shall be
+under the terms and conditions of this License, without any additional
+terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+### 6. Trademarks.
+
+This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of
+the Work and reproducing the content of the NOTICE file.
+
+### 7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor
+provides the Work (and each Contributor provides its Contributions) on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR
+A PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+### 8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including
+negligence), contract, or otherwise, unless required by applicable law
+(such as deliberate and grossly negligent acts) or agreed to in writing,
+shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or
+inability to use the Work (including but not limited to damages for loss
+of goodwill, work stoppage, computer failure or malfunction, or any and
+all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+### 9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may
+choose to offer, and charge a fee for, acceptance of support, warranty,
+indemnity, or other liability obligations and/or rights consistent with
+this License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf of any
+other Contributor, and only if You agree to indemnify, defend, and hold
+each Contributor harmless for any liability incurred by, or claims
+asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+##### END OF TERMS AND CONDITIONS
+
+## APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include the
+brackets!)  The text should be enclosed in the appropriate comment
+syntax for the file format. We also recommend that a file or class name
+and description of purpose be included on the same "printed page" as the
+copyright notice for easier identification within third-party archives.
+
+> #### Copyright [yyyy] [name of copyright owner]
+>
+> Licensed under the Apache License, Version 2.0 (the "License");
+> you may not use this file except in compliance with the License.
+> You may obtain a copy of the License at
+>
+> [http://www.apache.org/licenses/](http://www.apache.org/licenses/)
+>
+> Unless required by applicable law or agreed to in writing, software
+> distributed under the License is distributed on an "AS IS" BASIS,
+> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+> See the License for the specific language governing permissions and
+> limitations under the License.

package/README.md

@@ -0,0 +1,291 @@
+Juit I18n for Vue
+=================
+
+The `@juit/vue-i18n` package provides a _minimalistic_ plugin for VueJS (v. 3)
+to support basic internationalization (translations, numbers, and date formats).
+
+It heavily relies on the [`Intl.Locale`][1], [`Intl.NumberFormat`][2], and
+[`Intl.DateTimeFormat`][3] global objects widely supported by modern browsers.
+
+It also deeply integrates with TypeScript to provide compile-time checking on
+required translation languages and translation keys.
+
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Translating messages](#translating-messages)
+  - [Parameterizing translations](#parameterizing-translations)
+  - [Pluralization](#pluralization)
+- [Formatting numbers](#formatting-numbers)
+- [Formatting dates](#formatting-dates)
+- [Configuring Types](#configuring-types)
+- [Legal Stuff](#legal-stuff)
+
+
+## Installation
+
+As usual, install with NPM (or the cool package-manager du jour):
+
+```bash
+npm install '@juit/vue-i18n'
+```
+
+And add the plugin to your Vue app:
+
+```typescript
+import { createApp } from 'vue'
+import { i18n } from '@juit/vue-i18n'
+import MyApp from './app.vue'
+
+const app = createApp(MyApp).use(i18n, {
+  defaultLanguage: 'en',
+  translations: {
+    hello: {
+      en: 'Hello, world!',
+      de: 'Hallo, Welt!',
+    },
+  }
+})
+```
+
+
+## Configuration
+
+The plugin can be configured with a simple string (the `defaultLanguage`)
+described below, or some options:
+
+* `defaultLanguage`: the default language to use; all translations should be
+                     available in this language.
+* `translations`: an object containing the translations for the messages to
+                  translate, keyed by its identifier.
+* `formats`: configurations for number and date formatting:
+  * `dateTimeFormat`: a string (`short`, `medium`, `long`, or `full`) used to
+                      format date-and-time values, or the options to be
+                      provided to the `Intl.DateTimeFormat` constructor.
+  * `dateOnlyFormat`: a string (`short`, `medium`, `long`, or `full`) used to
+                      format dates, or the options to be provided to the
+                      `Intl.DateTimeFormat` constructor.
+  * `timeOnlyFormat`: a string (`short`, `medium`, `long`, or `full`) used to
+                      format times, or the options to be provided to the
+                      `Intl.DateTimeFormat` constructor.
+
+
+## Usage
+
+In any component `setup()` method, you can use the `useTranslator()` function
+to get a hold on the `Translator` configured for the current app.
+
+```typescript
+import { useTranslator } from '@juit/vue-i18n'
+
+const translator = useTranslator()
+```
+
+
+## Translating messages
+
+The base function to translate messages is exposed as `translator.t(...)` or
+(within components) the `$t(...)` function.
+
+This function takes a translation _key_ (specified in the configuration
+phase, see above).
+
+```typescript
+import { useTranslator } from '@juit/vue-i18n'
+
+const translator = useTranslator()
+
+const hello = translator.t('hello')
+// the "hello" string will be "Hello, world!" or "Hallo, Welt!"
+```
+
+It can also take an inline translation:
+
+```typescript
+import { useTranslator } from '@juit/vue-i18n'
+
+const translator = useTranslator()
+
+const panagram = translator.t({
+  en: 'The quick fox jumped over the lazy dog',
+  de: 'Franz jagt im komplett verwahrlosten Taxi quer durch Bayern'
+})
+```
+
+
+### Parameterizing translations
+
+Translations can include parameters by enclosing them in curly braces `{param}`.
+
+For example:
+
+```typescript
+const name = 'John Doe'
+
+const string: translator.t({
+  en: 'Your name is {name}'
+  de: 'Ihr Name ist {name}'
+}, { name })
+// This will result in either "Your name is John Doe" or "Ihr Name ist John Doe"
+```
+
+When parameters are numbers, those will be formatted as numbers:
+
+```typescript
+const string: translator.t({
+  en: 'Score {points} points'
+  de: 'Punktestand {points} Punkte'
+}, { points: 1234.56 })
+// This will result in "Score 1,234.56 points" or "Punktestand 1.234,56 Punkte"
+```
+
+
+### Pluralization
+
+The translator supports minimal rules for pluralization by separating
+translation messages with the `|` (pipe) character.
+
+Messages can contain two variants `singular|plural` or three variants
+`zero|singular|plural`, with each variant used when the reference number to
+pluralize is either zero, one, or another number:
+
+To contextualize the number, either use the `n` parameter, or use the `tc(...)`
+function which will take, as a second parameter, the reference number.
+
+For example:
+
+```typescript
+const string: translator.t({
+  en: 'no cats | one cat | {n} cats'
+  de: 'keine Katzen | eine Katze | {n} Katzen'
+}, { n })
+// This will result in "no cats" or "keine katzen" when "n" is zero,
+// "one cat" or "eine Katze" when "n" is 1, or
+// "1,234.56 cats" or "1.234,56 Katzen" when "n" is 1234.56
+```
+
+Is equivalent to:
+
+```typescript
+const string: translator.tc({
+  en: 'no cats | one cat | {n} cats'
+  de: 'keine Katzen | eine Katze | {n} Katzen'
+}, n)
+```
+
+
+## Formatting numbers
+
+The `n(...)` function can be used to format numbers in the current locale:
+
+```typescript
+import { useTranslator } from '@juit/vue-i18n'
+
+const translator = useTranslator()
+
+const number = translator.n(1234.5)
+// the "number" string will be "1,234.5", "1.234,5" or whatever locale specified
+```
+
+A currency can be specified as a second parameter for quick formatting:
+
+```typescript
+import { useTranslator } from '@juit/vue-i18n'
+
+const translator = useTranslator()
+
+const amount = translator.n(1234.5, 'USD')
+// the "amount" will be "$1,234.5", "1.234,5 $" or whatever locale specified
+```
+
+A full [`Intl.NumberFormatOptions`][4] set of options can also be specified
+as a second parameter to fine-tune the formatting.
+
+The default format can be specified when configuring the plugin as the
+`formats.numberFormat` option (intentionally, there is no default).
+
+
+## Formatting dates
+
+The `d(...)` function can be used to format date-and-time values in the current
+locale, together with the `d.date(...)` to format only dates, or `d.time(...)`
+to format only times.
+
+```typescript
+import { useTranslator } from '@juit/vue-i18n'
+
+const translator = useTranslator()
+
+const dateTime = translator.d(new Date()) // e.g. '03.02.2025, 18:08:05' in de-DE
+const dateOnly = translator.d.date(new Date()) // e.g. '03.02.2025' in de-DE
+const dateTime = translator.d.time(new Date()) // e.g. '18:08:05' in de-DE
+```
+
+A full [`Intl.DateTimeFormatOptions`][5] set of options can also be specified
+as a second parameter to fine-tune the formatting.
+
+The second parameter can also be a simple string `full`, `long`, `medium`, or
+`short`, as a shortcut to `options.dateStyle` or `options.timeStyle`.
+
+The default formatting options for each method can be specified at configuration
+time, using the `formats.dateTimeFormat`, `formats.dateOnlyFormat`, or
+`formats.timeOnlyFormat` parameters.
+
+By default, they are all set to `medium`.
+
+
+## Configuring Types
+
+One of the keys to this package is to provide compile-time safety for all
+translation languages (we don't want to forget to translate a message in
+a new language) and translation keys (we don't want to mistype a translation
+key by accident).
+
+To do so, we can _merge_ the `I18nConfiguration` interface of this package
+with our specific configurations. Two properties are expected to be defined
+in the configuration:
+
+* `languages`: the list of supported languages for the application. These
+               are ISO 639-1 language codes, and when specified, _every_
+               translation _must_ include a translation for each.
+* `translationKeys`: the list of translation keys known by the application.
+                     These are the arbitrary keys used to identify the
+                     messages to be translated with the `t` and `tc`
+                     methods of `Translator`.
+
+To configure the types, follow the example below:
+
+```typescript
+const translations = {
+  'hello': { en: 'Hello, world!', de: 'Hallo, Welt!' }
+} as const satisfies TranslationsOptions
+
+declare module '@juit/vue-i18n' {
+  export interface I18nConfiguration {
+    translationKeys: keyof typeof translations
+    languages: 'de' | 'en'
+  }
+}
+```
+
+In the example above, if any of the translation objects in our app is missing
+a language (either `en` or `de`), TypeScript will complain.
+
+In the same way, if we pass any other string but `hello` to `t(...)` or `tc(...)`,
+TypeScript will report the wrong key.
+
+
+## Legal Stuff
+
+* [Copyright Notice](NOTICE.md)
+* [License](LICENSE.md)
+
+
+[1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale
+[2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat
+[3]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat
+[4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
+[5]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options