Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrey-helldar
andrey-helldar committed Nov 22, 2023
1 parent f8df620 commit 1f8bd02
Show file tree
Hide file tree
Showing 29 changed files with 1,236 additions and 71 deletions.
24 changes: 16 additions & 8 deletions docs/laravel-lang.tree
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,31 @@
<toc-element topic="our-team.md" />
<toc-element topic="license.md" toc-title="License" />
</toc-element>
<toc-element topic="getting-started.md">
<toc-element topic="getting-started.md" id="toc-getting-started">
<toc-element topic="installation.md" />
<toc-element topic="configuration.md" />
</toc-element>
<toc-element topic="usage.md">
<toc-element topic="managing-locales.md">
<toc-element topic="manage-locales.md">
<toc-element topic="usage-add-locales.md" />
<toc-element topic="usage-update-locales.md" />
<toc-element topic="usage-reset-locales.md" />
<toc-element topic="usage-remove-locales.md" />
<toc-element topic="usage-available-locales.md" />
</toc-element>
<toc-element topic="usage-available-locales.md" />
<toc-element topic="usage-facade.md" />
<toc-element topic="usage-aliases.md" />
<toc-element topic="usage-list-of-locales.md" />
<toc-element topic="usage-native-locales.md" >
<toc-element topic="usage-native-locale-names.md" />
<toc-element topic="usage-native-country-names.md" />
<toc-element topic="usage-native-currency-names.md" />
</toc-element>
</toc-element>
<toc-element topic="plugins.md">
<toc-element topic="plugins-installation.md" />
<toc-element topic="plugins-official.md" />
<toc-element topic="plugins-community.md" />
</toc-element>
<toc-element topic="packages.md">
<toc-element topic="packages-common.md" />
Expand All @@ -50,11 +63,6 @@
<toc-element topic="packages-native-currency-names.md" />
<toc-element topic="packages-json-fallback.md" />
</toc-element>
<toc-element topic="plugins.md">
<toc-element topic="plugins-installation.md" />
<toc-element topic="plugins-official.md" />
<toc-element topic="plugins-community.md" />
</toc-element>
<toc-element topic="statuses.md">
<toc-element topic="statuses-lang.md" toc-title="Lang">
<toc-element topic="statuses-lang-af.md" />
Expand Down
33 changes: 22 additions & 11 deletions docs/topics/code-of-conduct.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,10 @@

## Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free
experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion,
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making
participation in our project and our community a harassment-free
experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of
experience, nationality, personal appearance, race, religion,
or sexual identity and orientation.

## Our Standards
Expand All @@ -26,27 +28,36 @@ Examples of unacceptable behavior by participants include:

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take
appropriate and fair corrective action in response to any instances
of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this
Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
issues, and other contributions that are not aligned to this
Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or
community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the
project or its community. Examples of representing a project or
community include using an official project e-mail address, posting via an official social media account, or acting as
an appointed representative at an online or offline event.
Representation of a project may be further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. The project team will review and investigate all complaints, and
will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. The
project team will review and investigate all complaints, and
will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain
confidentiality with regard to the reporter of an incident. Further
details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent
repercussions as determined by other members of the project's
leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), version 2.1.
This Code of Conduct is adapted from
the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), version 2.1.
184 changes: 184 additions & 0 deletions docs/topics/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,3 +44,187 @@ This is the contents of the published `%config-filename%` file:
> like `config/publisher.php`, `config/locales.php`, `config/laravel-lang.php`, etc.
>
> Therefore, we decided to use one configuration file for all our packages - this is `%config-filename%`.
## Alignment

When updating files, all comments from the final files are automatically deleted.
Unfortunately, [var_export](https://www.php.net/manual/en/function.var-export.php) does not know how to work with
comments.

Your file example:

```php
// auth.php
<?php

return [
/*
|--------------------------------------------------------------------------
| Authentication Language Lines
|--------------------------------------------------------------------------
|
| The following language lines are used during authentication for various
| messages that we need to display to the user. You are free to modify
| these language lines according to your application's requirements.
|
*/
'failed' => 'These credentials do not match our records 123456.',
'throttle' => 'Too many login attempts. Please try again in :seconds seconds.',
'foo' => 'bar',
];
```

An updated file like this:

```php
<?php

return [
'failed' => 'These credentials do not match our records.',
'foo' => 'bar',
'throttle' => 'Too many login attempts. Please try again in :seconds seconds.',
];
```

and example of `validation.php` file:

```php
// your file:
<?php

return [
/*
|--------------------------------------------------------------------------
| Validation Language Lines
|--------------------------------------------------------------------------
|
| The following language lines contain the default error messages used by
| the validator class. Some of these rules have multiple versions such
| as the size rules. Feel free to tweak each of these messages here.
|
*/
'accepted' => 'The :attribute must be accepted.',
'active_url' => 'The :attribute is not a valid URL.',

// many rules

'uuid' => 'The :attribute must be a valid UUID.',
/*
|--------------------------------------------------------------------------
| Custom Validation Language Lines
|--------------------------------------------------------------------------
|
| Here you may specify custom validation messages for attributes using the
| convention "attribute.rule" to name the lines. This makes it quick to
| specify a specific custom language line for a given attribute rule.
|
*/
'custom' => [
'name' => [
'required' => 'Custom message 1',
'string' => 'Custom message 2',
],
],
/*
|--------------------------------------------------------------------------
| Custom Validation Attributes
|--------------------------------------------------------------------------
|
| The following language lines are used to swap our attribute placeholder
| with something more reader friendly such as "E-Mail Address" instead
| of "email". This simply helps us make our message more expressive.
|
*/
'attributes' => [
'name' => 'Foo',
'bar' => 'Bar',
'baz' => 'Baz',
],
];
```

This is what it will look like after the update:

```php
<?php

return [
'accepted' => 'The :attribute must be accepted.',
'active_url' => 'The :attribute is not a valid URL.',

// many rules

'uuid' => 'The :attribute must be a valid UUID.',
'custom' => [
'name' => [
'required' => 'Custom message 1',
'string' => 'Custom message 2',
],
],
'attributes' => [
'bar' => 'Bar',
'baz' => 'Baz',
'email' => 'E-Mail address',
'first_name' => 'First Name',
'last_name' => 'Last Name',
'name' => 'Name',
'username' => 'Nickname',
],
];
```

## Smart Punctuation

When updating translation keys, you can also enable intelligent converts ASCII quotes, dashes, and ellipses to their
Unicode.

For example:

```json
{
"Some": "\"It's super-configurable... you can even use additional extensions to expand its capabilities -- just like this one!\""
}
```

Will result in files:

```json
{
"Some": "“It’s super-configurable… you can even use additional extensions to expand its capabilities – just like this one!”"
}
```

This option is enabled in the `%config-filename%` file:

```php
'smart_punctuation' => [
'enable' => true,

'common' => [
'double_quote_opener' => '“',
'double_quote_closer' => '”',
'single_quote_opener' => '‘',
'single_quote_closer' => '’',
],

'locales' => [
Locales::FRENCH->value => [
'double_quote_opener' => '“',
'double_quote_closer' => '”',
'single_quote_opener' => '‘',
'single_quote_closer' => '’',
],

Locales::UKRAINIAN->value => [
'double_quote_opener' => '«',
'double_quote_closer' => '»',
'single_quote_opener' => '‘',
'single_quote_closer' => '’',
],
],
],
```

You can also set different rules for any localization.

By default, conversion is disabled.
3 changes: 2 additions & 1 deletion docs/topics/development.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# Development

Start typing here...
- [Contributing](contributing.md)
- [Contributor Covenant Code of Conduct](code-of-conduct.md)
6 changes: 5 additions & 1 deletion docs/topics/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
# Getting Started

Start typing here...
- [Installation](installation.md)
- [Configuration](configuration.md)
- [Aliases](configuration.md#aliases)
- [Alignment](configuration.md#alignment)
- [Smart Punctuation](configuration.md#smart-punctuation)
Loading

0 comments on commit 1f8bd02

Please sign in to comment.