Skip to content

Update docs for Config 2.x support #54

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Update docs for Config 2.x support #54

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
88b9dfb
Update docs for Config 2.x support
andrey-helldar May 6, 2025
224612a
Merge branch 'main' into patch/config-2.x
andrey-helldar May 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
289 changes: 140 additions & 149 deletions docs/topics/configuration.topic
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,142 +14,140 @@

<chapter title="Publish" id="publish">
<p>
Optionally, you can publish the config file with:
Optionally, you can publish the config files with:
</p>
<code-block lang="bash">
php artisan vendor:publish --tag="%package-vendor-tag%"
</code-block>
<p>
This is the contents of the published <code>%config-filename%</code> file:
This command will publish the configuration files for all projects. To publish settings for specific packages, use the console commands:
</p>
<code-block
lang="php"
src="%config-url%"
include-lines="7-"
collapsed-title="Show configuration"
collapsible="true"
/>
</chapter>

<chapter title="Inline" id="inline">
<p>
The <code>inline</code> option determines what type of files to use when updating language files.
</p>

<list>
<li><code>true</code> means inline files will be used.</li>
<li><code>false</code> means that default files will be used.</li>
</list>

<p>
For example, the difference between them can be seen here:
</p>

<code-block>
The :attribute must be accepted. // default
This field must be accepted. // inline
<code-block lang="bash">
php artisan vendor:publish --tag="%package-vendor-tag-main%"
php artisan vendor:publish --tag="%package-vendor-tag-models%"
php artisan vendor:publish --tag="%package-vendor-tag-routes%"
php artisan vendor:publish --tag="%package-vendor-tag-punctuation%"
php artisan vendor:publish --tag="%package-vendor-tag-translators%"
</code-block>

<include from="library-descriptions.topic" element-id="available-config-option" />

<code-block
lang="php"
src="%config-url%"
include-lines="8,17,279"
/>
</chapter>

<chapter title="Alignment" id="alignment">
<p>
The <code>align</code> option defines the alignment of values relative
to each other when processing localization files.
</p>

<p>
When updating files, all comments from the final files are automatically deleted.
Unfortunately, <a href="https://www.php.net/manual/en/function.var-export.php">var_export</a>
does not know how to work with comments.
</p>
<p>
Your file example:
</p>
<code-block lang="php" src="configuration-alignment-auth-before.php" include-lines="3-" />
<p>
An updated file like this:
</p>
<code-block lang="php" src="configuration-alignment-auth-after.php" include-lines="3-" />
<p>
and example of <code>validation.php</code> file:
</p>
<code-block
lang="php"
src="configuration-alignment-validation-before.php"
include-lines="3-"
collapsed-title="Show content"
collapsible="true"
/>
<p>
This is what it will look like after the update:
</p>
<code-block lang="php" src="configuration-alignment-validation-after.php" include-lines="3-" />

<include from="library-descriptions.topic" element-id="available-config-option" />
<chapter title="Main" id="main">
<note>
Config filename is <code>%config-filename-main%</code>.
</note>

<code-block
lang="php"
src="%config-url%"
include-lines="8,27,279"
src="https://raw.githubusercontent.com/Laravel-Lang/config/2.x/config/main.php"
include-lines="5-"
/>
</chapter>

<chapter title="Aliases" id="aliases">
<p>
If you want to name codes differently, such as <code>de-DE</code> instead of <code>de</code> or
<code>de-CH</code> instead of <code>de_CH</code>, you can define
<code>aliases</code> in the <a href="configuration.topic#aliases">configuration file</a>.
</p>
<p>
After that, all adding, updating, and deleting actions will automatically use the specified aliases in
the <code>%config-filename%</code> config file:
</p>

<code-block lang="php" src="usage-aliases.php" include-lines="3-" />

<p>
If the
<code>%config-filename%</code> file already exists, then you can add the aliases key in it and specify the
desired
<code>aliases</code> using a data array.
</p>
<p>
After this, you can, for example, add new localizations by specifying both the main code and its alias:
</p>

<code-block lang="bash">
<chapter title="Inline" id="inline">
<p>
The <code>inline</code> option determines what type of files to use when updating language files.
</p>

<list>
<li><code>true</code> means inline files will be used.</li>
<li><code>false</code> means that default files will be used.</li>
</list>

<p>
For example, the difference between them can be seen here:
</p>

<code-block>
The :attribute must be accepted. // default
This field must be accepted. // inline
</code-block>
</chapter>

<chapter title="Alignment" id="alignment">
<p>
The <code>align</code> option defines the alignment of values relative
to each other when processing localization files.
</p>

<p>
When updating files, all comments from the final files are automatically deleted.
Unfortunately, <a href="https://www.php.net/manual/en/function.var-export.php">var_export</a>
does not know how to work with comments.
</p>
<p>
Your file example:
</p>
<code-block lang="php" src="configuration-alignment-auth-before.php" include-lines="3-" />
<p>
An updated file like this:
</p>
<code-block lang="php" src="configuration-alignment-auth-after.php" include-lines="3-" />
<p>
and example of <code>validation.php</code> file:
</p>
<code-block
lang="php"
src="configuration-alignment-validation-before.php"
include-lines="3-"
collapsed-title="Show content"
collapsible="true"
/>
<p>
This is what it will look like after the update:
</p>
<code-block lang="php" src="configuration-alignment-validation-after.php" include-lines="3-" />
</chapter>

<chapter title="Aliases" id="aliases">
<p>
If you want to name codes differently, such as <code>de-DE</code> instead of <code>de</code> or
<code>de-CH</code> instead of <code>de_CH</code>, you can define
<code>aliases</code> in the <a href="configuration.topic#aliases">configuration file</a>.
</p>
<p>
After that, all adding, updating, and deleting actions will automatically use the specified aliases in
the <code>%config-filename-main%</code> config file:
</p>

<code-block lang="php" src="usage-aliases.php" include-lines="3-" />

<p>
If the
<code>%config-filename-main%</code> file already exists, then you can add the aliases key in it and specify the
desired
<code>aliases</code> using a data array.
</p>
<p>
After this, you can, for example, add new localizations by specifying both the main code and its alias:
</p>

<code-block lang="bash">
%command-add% de de_CH
</code-block>

<p>
Installed locales will use the specified aliases as folder names for PHP translations and file names for
JSON translations:
</p>

<code-block lang="plain text">
lang
de-CH
de-DE
</code-block>
<p>
Installed locales will use the specified aliases as folder names for PHP translations and file names for
JSON translations:
</p>

<code-block lang="plain text">
lang
de-CH
de-DE
</code-block>
</chapter>
</chapter>

<include from="library-descriptions.topic" element-id="available-config-option" />
<chapter title="Smart Punctuation" id="smart_punctuation">
<note>
Config filename is <code>%config-filename-punctuation%</code>.
</note>

<code-block
lang="php"
src="%config-url%"
include-lines="8,38-41,279"
src="https://raw.githubusercontent.com/Laravel-Lang/config/2.x/config/punctuation.php"
include-lines="5-"
/>
</chapter>

<chapter title="Smart Punctuation" id="smart_punctuation">
<p>
When updating translation keys, you can also enable intelligent converts ASCII quotes, dashes,
and ellipses to their Unicode.
Expand All @@ -167,16 +165,6 @@

<code-block lang="json" src="smart-punctuation-after.json" />

<include from="library-descriptions.topic" element-id="available-config-option" />

<code-block
lang="php"
src="%config-url%"
include-lines="6,7-8,52-91,279"
collapsed-title="Show settings"
collapsible="true"
/>

<p>
You can also set different rules for any localization.
</p>
Expand All @@ -186,37 +174,39 @@
</chapter>

<chapter title="Routes" id="routes">
<note>
Config filename is <code>%config-filename-routes%</code>.
</note>

<code-block
lang="php"
src="https://raw.githubusercontent.com/Laravel-Lang/config/2.x/config/routes.php"
include-lines="5-"
/>

<p>
When using the package to work with
<a href="packages-routes.topic">routing</a>
, you can override the default values of key names.
</p>
</chapter>

<chapter title="Models" id="models">
<note>
Config filename is <code>%config-filename-models%</code>.
</note>

<p>
This option is enabled in the <code>%config-filename%</code> file:
</p>
<code-block
lang="php"
src="%config-url%"
include-lines="5,7-8,99,112-118,125-126,134,142,145-147,150-155,159-168,279"
src="https://raw.githubusercontent.com/Laravel-Lang/config/2.x/config/models.php"
include-lines="5-"
/>
</chapter>

<chapter title="Models" id="models">
<p>
You can define default parameter values when using the
<a href="packages-models.topic">%repository-title-models%</a> package.
</p>

<p>
This setting available in the <code>%config-filename%</code> file:
</p>
<code-block
lang="php"
src="%config-url%"
include-lines="8,176,187,196-198,206-207,279"
/>

<p>
The <code>suffix</code> parameter is used to specify
the suffix of the models to which the translation repository belongs.
Expand All @@ -231,20 +221,21 @@
</code-block>
</chapter>

<chapter title="Translator" id="translator">
<chapter title="Translators" id="translators">
<note>
Config filename is <code>%config-filename-translators%</code>.
</note>

<code-block
lang="php"
src="https://raw.githubusercontent.com/Laravel-Lang/config/2.x/config/translators.php"
include-lines="5-"
/>

<p>
Here you can not only activate default translators, but also create your own.
You can read more about this on the
<a href="packages-translator.topic">%repository-title-translator%</a> package information page.
</p>

<p>
This setting available in the <code>%config-filename%</code> file:
</p>
<code-block
lang="php"
src="%config-url%"
include-lines="8,217,228-260,276-"
/>
</chapter>
</topic>
6 changes: 0 additions & 6 deletions docs/topics/library-descriptions.topic
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,6 @@
</code-block>
</snippet>

<snippet id="available-config-option">
<p>
This option is available in the <code>%config-filename%</code> file:
</p>
</snippet>

<snippet id="route-caching-support">
<note>
<p>
Expand Down
14 changes: 11 additions & 3 deletions docs/v.list
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,11 @@
<var name="command-reset" value="php artisan lang:reset" />
<var name="command-update" value="php artisan lang:update" />
<var name="command-update-simple" value="lang:update" />
<var name="config-filename" value="config/localization.php" />
<var name="config-filename-basename" value="localization" />
<var name="config-url" value="https://raw.githubusercontent.com/Laravel-Lang/config/1.x/config/public.php" />
<var name="config-filename-main" value="config/localization.php" />
<var name="config-filename-models" value="config/localization-models.php" />
<var name="config-filename-routes" value="config/localization-routes.php" />
<var name="config-filename-punctuation" value="config/localization-punctuation.php" />
<var name="config-filename-translators" value="config/localization-translators.php" />
<var name="install-actions" value="composer require --dev laravel-lang/actions" />
<var name="install-attributes" value="composer require --dev laravel-lang/attributes" />
<var name="install-common" value="composer require laravel-lang/common" />
Expand Down Expand Up @@ -66,6 +68,12 @@
<var name="package-status-generator" value="laravel-lang/status-generator" />
<var name="package-translator" value="laravel-lang/translator" />
<var name="package-vendor-tag" value="localization" />
<var name="package-vendor-tag-all" value="localization-all" />
<var name="package-vendor-tag-main" value="localization" />
<var name="package-vendor-tag-models" value="localization-models" />
<var name="package-vendor-tag-punctuation" value="localization-punctuation" />
<var name="package-vendor-tag-routes" value="localization-routes" />
<var name="package-vendor-tag-translators" value="localization-translators" />
<var name="repository-assign-bugs" value="andrey-helldar" />
<var name="repository-bugs" value="common" />
<var name="repository-label-actions" value="actions" />
Expand Down