tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 12:05:37 +00:00
Code Issues Projects Releases Wiki Activity

Review and tidy up contributing documentation.

Browse Source
This commit is contained in:
Will Rossiter 2014-09-26 19:49:44 +12:00 committed by Cam Findlay
parent 084286af4c
commit f633236e78
7 changed files with 295 additions and 295 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/en/05_Contributing/00_Issues_and_Bugs.md
View File

@ -1,3 +1,6 @@
title: Bug Reports
summary: Report bugs or problems with SilverStripe, feature requests or other issues.
# Contributing Issues and Opinions # Contributing Issues and Opinions
## Reporting Bugs ## Reporting Bugs
@ -31,7 +34,7 @@ If the issue does look like a new bug:
Ensure you give us enough information to diagnose your issue: Ensure you give us enough information to diagnose your issue:
* Switch your site to "[dev mode](/topics/debugging)". Paste any PHP errors with their stacktraces. A generic "Server Error" message is not enough information. * Switch your site to "[dev mode](/developer_guides/debugging)". Paste any PHP errors with their stacktraces. A generic "Server Error" message is not enough information.
* If you suspect a JavaScript or CSS bug, check if it appears in other browsers * If you suspect a JavaScript or CSS bug, check if it appears in other browsers
* Use the [Chrome dev tools](https://developers.google.com/chrome-developer-tools/docs/overview) or [Firefox dev tools](https://developer.mozilla.org/en-US/docs/Tools) * Use the [Chrome dev tools](https://developers.google.com/chrome-developer-tools/docs/overview) or [Firefox dev tools](https://developer.mozilla.org/en-US/docs/Tools)
* Use the JavaScript console in your browser to determine if any errors happened there, and paste the complete info into issue description. * Use the JavaScript console in your browser to determine if any errors happened there, and paste the complete info into issue description.
@ -45,22 +48,26 @@ with you to develop a fix.
## Feature Requests ## Feature Requests
<div class="warning" markdown='1'> <div class="warning" markdown='1'>
Please don't file "feature requests" as issues. If there's a new feature you'd like to see Please don't file "feature requests" as Github issues. If there's a new feature
in SilverStripe, you either need to write it yourself (and [submit a pull request](/misc/contributing/code)) you'd like to see in SilverStripe, you either need to write it yourself (and
or convince somebody else to write it for you. Any "wishlist" type issues without code attached [submit a pull request](/misc/contributing/code)) or convince somebody else to
can be expected to be closed as soon as they're reviewed. write it for you. Any "wishlist" type issues without code attached can be
expected to be closed as soon as they're reviewed.
</div> </div>
In order to gain interest and feedback in your feature, we encourage you to present In order to gain interest and feedback in your feature, we encourage you to
it to the community through the [forums](http://silverstripe.org/forums), [core mailinglist](http://groups.google.com/group/silverstripe-dev) or on [IRC](http://silverstripe.org/irc). present it to the community through the [forums](http://silverstripe.org/forums),
[core mailinglist](http://groups.google.com/group/silverstripe-dev) or on
[IRC](http://silverstripe.org/irc).
## Reporting Security Issues ## Reporting Security Issues
Report security issues to [security@silverstripe.com](mailto:security@silverstripe.com). See our "[Release Process](release-process)" documentation for more info, and read our guide on [how to write secure code](/topics/security). Report security issues to [security@silverstripe.com](mailto:security@silverstripe.com).
See our "[Release Process](release-process)" documentation for more info, and
read our guide on [how to write secure code](/topics/security).
## Sharing your Opinion ## Sharing your Opinion
* [silverstripe.org/forums](http://silverstripe.org/forums): Forums on silverstripe.org * [silverstripe.org/forums](http://silverstripe.org/forums): Forums on silverstripe.org
* [silverstripe-dev](http://groups.google.com/group/silverstripe-dev): Core development mailinglist * [silverstripe-dev](http://groups.google.com/group/silverstripe-dev): Core development mailinglist
* [silverstripe-documentation](http://groups.google.com/group/silverstripe-documentation): Documentation team mailing list * [silverstripe-documentation](http://groups.google.com/group/silverstripe-translators): Translation team mailing list
* [silverstripe-translators](http://groups.google.com/group/silverstripe-translators): Translation team mailing list

16
docs/en/05_Contributing/02_Release_Process.md
View File

@ -1,3 +1,5 @@
summary: Describes the process followed for "core" releases.
# Release Process # Release Process
Describes the process followed for "core" releases (mainly the `framework` and `cms` modules). Describes the process followed for "core" releases (mainly the `framework` and `cms` modules).
@ -68,7 +70,7 @@ new minor release. These changes can be performed in a single minor release with
### Micro releases ### Micro releases
Micro releases are issued about every two months for the latest release, typically for security reasons. Micro releases are issued about every two months for the latest release, typically for security reasons.
You can safely upgrade to those releases (after reading the [upgrading](/installation/upgrading) guidelines). You can safely upgrade to those releases (after reading the [upgrading](/upgrading/) guidelines).
For example, *2.3.6* was released in February 2010, followed by *2.3.7* in March 2010. For example, *2.3.6* was released in February 2010, followed by *2.3.7* in March 2010.
### Supported versions ### Supported versions
@ -100,8 +102,9 @@ How to deprecate an API:
* Deprecations should just be committed to pre-release branches, ideally before they enter the "beta" phase. * Deprecations should just be committed to pre-release branches, ideally before they enter the "beta" phase.
If deprecations are introduced after this point, their target version needs to be increased by one. If deprecations are introduced after this point, their target version needs to be increased by one.
* Make sure that the old deprecated function works by calling the new function - don't have duplicated code! * Make sure that the old deprecated function works by calling the new function - don't have duplicated code!
* The commit message should contain an `API` prefix (see ["commit message format"](/misc/contributing/code#commit-messages)) * The commit message should contain an `API` prefix (see ["commit message format"](code#commit-messages))
* Deprecated APIs can be removed after developers had a chance to react to the changes. As a rule of thumb, leave the code with the deprecation warning in for at least three micro releases. Only remove code in a minor or major release. * Deprecated APIs can be removed after developers had a chance to react to the changes. As a rule of thumb, leave the
code with the deprecation warning in for at least three micro releases. Only remove code in a minor or major release.
Here's an example for replacing `Director::isDev()` with a (theoretical) `Env::is_dev()`: Here's an example for replacing `Director::isDev()` with a (theoretical) `Env::is_dev()`:
@ -124,9 +127,9 @@ released version (e.g. 3.1.1), the target version becomes 3.2 instead.
### Reporting an issue ### Reporting an issue
Report security issues to [security@silverstripe.com](mailto:security@silverstripe.com). Report security issues to [security@silverstripe.com](mailto:security@silverstripe.com).
Please don't file security issues in our [bugtracker](/misc/contributing/issues). Please don't file security issues in our [bugtracker](issues_and_bugs).
### Acknowledgement and disclosure ### Acknowledgment and disclosure
In the event of a confirmed vulnerability in SilverStripe core, we will take the following actions: In the event of a confirmed vulnerability in SilverStripe core, we will take the following actions:
@ -148,7 +151,8 @@ webserver access logs (if a hack is suspected), any other services and web packa
### Severity rating ### Severity rating
Each [security release](http://www.silverstripe.org/security-releases/) includes an overall severity rating and one for each vulnerability. The rating indicates how important an update is: Each [security release](http://www.silverstripe.org/security-releases/) includes an overall severity rating and one for
each vulnerability. The rating indicates how important an update is:
| Severity | Description | | Severity | Description |
|---------------|-------------| |---------------|-------------|

123
docs/en/05_Contributing/03_Documentation.md
View File

@ -1,38 +1,48 @@
title: Documentation
summary: Developer and CMS User Help Documentation.
# Contributing Documentation # Contributing Documentation
[« Back to Contributing page](.) Documentation for a software project is a continued and collaborative effort, we encourage everybody to contribute, from
simply fixing spelling mistakes, to writing recipes, reviewing existing documentation, and translating the whole thing.
Documentation for a software project is a continued and collaborative effort, Modifying documentation requires basic [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) and
we encourage everybody to contribute, from simply fixing spelling mistakes, to writing recipes/howtos, [Markdown](http://daringfireball.net/projects/markdown/) knowledge, and a GitHub user account.
reviewing existing documentation, and translating the whole thing.
Modifying documentation requires basic [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) and
[Markdown](http://daringfireball.net/projects/markdown/)/[SSMarkdown](../ss-markdown) knowledge,
and a GitHub user account.
## Editing online ## Editing online
The easiest way of making a change to the documentation is by clicking the "Edit this page" link at The easiest way of making a change to the documentation is by clicking the "Edit this page" link at the bottom of the
the bottom of the page you want to edit. Alternativly, you can find the appropriate .md file in page you want to edit. Alternativly, you can find the appropriate .md file in the
the [github.com/silverstripe/silverstripe-framework](https://github.com/silverstripe/silverstripe-framework/tree/3.0/docs/) repository [github.com/silverstripe/silverstripe-framework](https://github.com/silverstripe/silverstripe-framework/tree/master/docs/)
and press the "edit" button. You will need a GitHub account to do this. You should make the changes in the lowest branch they apply to. repository and press the "edit" button. **You will need a free GitHub account to do this**.
* After you have made your change, describe it in the "commit summary" and "extended description" fields below, and press "Commit Changes".
* After that you will see form to submit a Pull Request. You should just be able to submit the form, and your changes will be sent to the core team for approval. * After you have made your change, describe it in the "commit summary" and "extended description" fields below, and
press "Commit Changes".
* After that you will see form to submit a Pull Request. You should just be able to submit the form, and your changes
will be sent to the core team for approval.
<div class="warning" markdown='1'>
You should make the changes in the lowest branch they apply to. For instance, if you fix a spelling issue that you
found in the 3.1 documentation, submit your fix to that branch in Github and it'll be copied to the master (3.2)
version of the documentation automatically. *Don't submit multiple pull requests*.
</div>
## Editing on your computer ## Editing on your computer
If you prefer to edit the content on your local machine, you can "[fork](http://help.github.com/forking/)" If you prefer to edit the content on your local machine, you can "[fork](http://help.github.com/forking/)" the
the [github.com/silverstripe/silverstripe-framework](http://github.com/silverstripe/silverstripe-framework) [github.com/silverstripe/silverstripe-framework](http://github.com/silverstripe/silverstripe-framework) and
and [github.com/silverstripe/silverstripe-cms](http://github.com/silverstripe/silverstripe-cms) [github.com/silverstripe/silverstripe-cms](http://github.com/silverstripe/silverstripe-cms) repositories and send us
repositories and send us "[pull requests](http://help.github.com/pull-requests/)". If you have "[pull requests](http://help.github.com/pull-requests/)". If you have downloaded SilverStripe or a module, chances are
downloaded SilverStripe or a module, chances are that you already have these checkouts. that you already have these repositories on your machine.
The documentation is kept alongside the source code in the `docs/` subfolder. The documentation is kept alongside the source code in the `docs/` subfolder of any SilverStripe module, framework or
CMS folder.
**Note:** If you submit a new feature or an API change, we strongly recommend that your patch <div class="warning" markdown='1'>
includes updates to the necessary documentation. This helps prevent our documentation from If you submit a new feature or an API change, we strongly recommend that your patch includes updates to the necessary
getting out of date. documentation. This helps prevent our documentation from getting out of date.
</div>
## Repositories ## Repositories
@ -46,64 +56,46 @@ Its contents are fetched from different releases automatically every couple of m
## Source Control ## Source Control
In order to balance editorial control with effective collaboration, we keep In order to balance editorial control with effective collaboration, we keep documentation alongside the module source
documentation alongside the module source code, e.g. in `framework/docs/`, code, e.g. in `framework/docs/`, or as code comments within PHP code. Contributing documentation is the same process as
or as code comments within PHP code. providing any other patch (see [Contributing code](code)).
Contributing documentation is the same process as providing any other patch
(see [Contributing code](code)).
## What to write ## What to write
* **API Docs**: Written alongside source code and displayed on [api.silverstripe.com](http://api.silverstripe.org).
This documents the low-level, technical usage of a class, method or property.
Not suited for longer textual descriptions, due to the limited support of PHPDoc formatting for headlines.
* **Tutorials**: The first contact for new users, guiding them step-by-step through achievable projects, in a book-like style.
*Example: Building a basic site*
* **Topics**: Provides an overview on how things fit together, the "conceptual glue" between APIs and features.
This is where most documentation should live, and is the natural "second step" after finishing the tutorials.
*Example: Templates, Testing, Datamodel*
* **Howto**: Recipes that solve a specific task or problem, rather than describing a feature.
*Example: Export DataObjects as CSV, Customizing TinyMCE in the CMS*
* **Reference**: Complements API docs in providing deeper introduction into a specific API. Most documentation
should fit elsewhere. *Example: ModelAdmin*
* **Misc**: "Meta" documentation like coding conventions that doesn't directly relate to a feature or API.
See [What to write (jacobian.org)](http://jacobian.org/writing/great-documentation/what-to-write/) for an excellent See [What to write (jacobian.org)](http://jacobian.org/writing/great-documentation/what-to-write/) for an excellent
introduction to the different types of documentation, and [Producing OSS: "Documentation"](http://producingoss.com/en/getting-started.html#documentation) introduction to the different types of documentation, and
for good rules of thumb for documenting opensource software. [Producing OSS: "Documentation"](http://producingoss.com/en/getting-started.html#documentation) for good rules of thumb
for documenting open source software.
## Structure ## Structure
* Keep documentation lines to 120 characters.
* Don't duplicate: Search for existing places to put your documentation. Do you really require a new page, or just a new paragraph * Don't duplicate: Search for existing places to put your documentation. Do you really require a new page, or just a new paragraph
of text somewhere? of text somewhere?
* Use PHPDoc in source code: Leave lowlevel technical documentation to code comments within PHP, in [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) format. * Use PHPDoc in source code: Leave lowlevel technical documentation to code comments within PHP, in [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) format.
* Use Markdown in Developer Guides: We have a slightly customized version of Markdown called [SSMarkdown](../ss-markdown) * API and Developer Guides complement each other: Both forms of documenting source code (API and Developer Guides) are valuable resources.
* API and Developer Guides complement each other: Both forms of documenting sourcecode (API and Developer Guides) are valueable ressources.
* Provide context: Give API documentation the "bigger picture" by referring to Developer Guides inside your PHPDoc. * Provide context: Give API documentation the "bigger picture" by referring to Developer Guides inside your PHPDoc.
* Make your documentation findable: Documentation lives by interlinking content, so please make sure your contribution doesn't become an * Make your documentation findable: Documentation lives by interlinking content, so please make sure your contribution doesn't become an
inaccessible island. Your page should at least be linked on the index page in the same folder. It can also appear inaccessible island. Your page should at least be linked on the index page in the same folder. It can also appear
as "related content" on other resource (e.g. `/topics/search` might link to `howto/search-dataobjects`). as "related content" on other resource (e.g. `/topics/search` might link to `howto/search-dataobjects`).
* Avoid FAQs: FAQs are not a replacement of a coherent, well explained documentation. If you've done a good job
documenting, there shouldn't be any "frequently asked questions" left ;)
* Commit early and often: You don't need to completely finish documentation, as long as you mark areas needing refinement.
* Every file should have exactly one `<h1>` headline, roughly matching the filename. It should be short enough to be
used in table of content lists.
## Writing Style ## Writing Style
* Write in second plural form: Use "we" instead of "I". It gives the text an instructive and collaborative style. * Write in second plural form: Use "we" instead of "I". It gives the text an instructive and collaborative style.
* Its okay to address the reader: For example "First you'll install a webserver" is good style. * It's okay to address the reader: For example "First you'll install a webserver" is good style.
* Write in an active and direct voice * Write in an active and direct voice.
* Mark up correctly: Use preformatted text, emphasis and bold to make technical writing more "scannable". * Mark up correctly: Use preformatted text, emphasis and bold to make technical writing more "scannable".
* Avoid FAQs: FAQs are not a replacement of a coherent, well explained documentation. If you've done a good job
documenting, there shouldn't be any "frequently asked questions" left ;)
## Highlighted blocks ## Highlighted blocks
There are several built-in block styles for highlighting a paragraph of text. There are several built-in block styles for highlighting a paragraph of text. Please use these graphical elements
Please use these graphical elements sparingly. sparingly.
<div class="hint" markdown='1'> <div class="hint" markdown='1'>
"Tip box": Adds, deepens or accents information in the main text. "Tip box": Adds, deepens or accents information in the main text. Can be used for background knowledge, or "see also"
Can be used for background knowledge, or "see also" links. links.
</div> </div>
Code: Code:
@ -113,8 +105,8 @@ Code:
</div> </div>
<div class="notice" markdown='1'> <div class="notice" markdown='1'>
"Notification box": Technical notifications relating to the main text. "Notification box": Technical notifications relating to the main text. For example, notifying users about a deprecated
For example, notifying users about a deprecated feature. feature.
</div> </div>
Code: Code:
@ -124,9 +116,8 @@ Code:
</div> </div>
<div class="warning" markdown='1'> <div class="warning" markdown='1'>
"Warning box": Highlight a severe bug or technical issue requiring "Warning box": Highlight a severe bug or technical issue requiring a users attention. For example, a code block with
a users attention. For example, a code block with destructive functionality destructive functionality might not have its URL actions secured to keep the code shorter.
might not have its URL actions secured to keep the code shorter.
</div> </div>
Code: Code:
@ -140,10 +131,10 @@ on placing HTML blocks inside Markdown.
## Translating Documentation ## Translating Documentation
Documentation is kept alongside the source code, typically in a module subdirectory like `framework/docs/en/`. Documentation is kept alongside the source code, typically in a module subdirectory like `framework/docs/en/`. Each
Each language has its own subfolder, which can duplicate parts or the whole body of documentation. language has its own subfolder, which can duplicate parts or the whole body of documentation. German documentation
German documentation would for example live in `framework/docs/de/`. would for example live in `framework/docs/de/`. The
The [docsviewer](https://github.com/silverstripe/silverstripe-docsviewer) module that drives [docsviewer](https://github.com/silverstripe/silverstripe-docsviewer) module that drives
[doc.silverstripe.org](http://doc.silverstripe.org) automatically resolves these subfolders into a language dropdown. [doc.silverstripe.org](http://doc.silverstripe.org) automatically resolves these subfolders into a language dropdown.
## Further reading ## Further reading

130
docs/en/05_Contributing/04_Translation.md
View File

@ -1,130 +0,0 @@
# Contributing Translations for the User Interface
[« Back to Contributing page](../contributing)
We are always looking for new translators. Even if a specific language already is translated and has an official maintainer, we can use helping hands in reviewing and updating translations. Important: It is perfectly fine if you only have time for a partial translation or quick review work - our system accomodates many people collaborating on the same language.
The content for UI elements (button labels, field titles) and instruction texts shown in the CMS and elsewhere is stored in the PHP code for a module (see [i18n](/topics/i18n)). All content can be extracted as a "language file", and uploaded to an online translation editor interface. SilverStripe is already translated in over 60 languages, and we're relying on native speakers to keep these up to date, and of course add new languages.
Please register a free translator account to get started, even if you just feel like fixing up a few sentences.
## The online translation tool
We provide a GUI for translations through [transifex.com](http://transifex.com). If you don't have an account yet, please follow the links there to sign up. Select a project from the [list of translatable modules](https://www.transifex.com/accounts/profile/silverstripe/) and start translating online!
For all modules listed there, we automatically import new master strings
as they get committed to the various codebases (via a nightly task),
so you're always translating on the latest and greatest version.
You can check the last successful push of the translation master strings in our
[public continuous integration server](http://teamcity.silverstripe.com/viewType.html?buildTypeId=bt112) (select "log in as guest").
## FAQ
### What happened to getlocalization.com?
We migrated from getlocalization.com to transifex in mid 2013.
### How do I translate a module not listed on Transifex?
Most modules maintained by SilverStripe are on Transifex.
For other modules, have a look in the module README if there's any specific instructions.
If there aren't, you'll need to translate the YAML files directly. If the module is on github,
you can create a fork, edit the files, and send back your pull request all directly on
the website ([instructions](https://help.github.com/articles/fork-a-repo)).
### How do I translate substituted strings? (e.g. '%s' or '{my-variable}')
You don't have to - if the english master-string reads 'Hello %s', your german translation would be 'Hallo %s'. Strings prefixed by a percentage-sign are automatically replaced by silverstripe with dynamic content. See http://php.net/sprintf for details. The newer `{my-variable}` format works the same way,
but makes its intent clearer, and allows reordering of placeholders in your translation.
### Do I need to convert special characters (e.g. HTML-entities)?
Special characters (such as german umlauts) need to be entered in their native form. Please don't use HTML-entities ("&amp;auml;" instead of "ä"). Silverstripe stores and renders most strings in UTF8 (Unicode) format.
### How can I check out my translation in the interface?
Currently translated entities are not directly factored into code (for security reasons and release/review-control), so you can't see them straight away.
It is strongly encouraged that you check your translation this way, as its a good way to doublecheck your translation works in the right context.
Please use our [daily-builds](http://www.silverstripe.org/daily-builds/) for your local installation, to ensure you're looking at the most up to date interface. See "Download Translations" above
to find out how to retrieve the latest translation files.
### Can I change a translation just for one SilverStripe version?
While we version control our translation files like all other source code,
the online translation tool doesn't have the same capabilities.
A translated string (as identified by its unique "entity name")
is assumed to work well in all releases. If the interface changes
in a non-trivial fashion, the new translations required should
have new identifiers as well.
Example: We renamed the "Security" menu title to "Users"
in our 3.0 release. As it would confuse users of older versions
unnecessarily, we should be using a new entity name for this,
and avoid the change propagating to an older SilverStripe version.
### How do I change my interface language?
Once you've logged into the CMS, you should see the text "Hi <your name>" near the top left, you can click this to edit your profile ([direct link](http://localhost/admin/myprofile/)). You can then set the "interface language" from a dropdown which automatically includes all found translations (based on the files in the `/lang` folders).
### I've found a piece of untranslatable text
It is entirely possible that we missed certain strings in preparing Silverstripe for translation-support. If you're technically minded, please read [i18n](/topics/i18n) on how to make it translatable. Otherwise just post your findings to the forum.
### How do I add my own module?
Once you've built a translation-enabled module, you can run the "textcollector" on your local installation for this specific module (see [i18n](/topics/i18n)). This should find all calls to `_t()` in php and template files, and generate a new lang file with the default locale (path: <mymodule>/lang/en.yml). Upload this file to the
online translation tool, and wait for hyour translators to do their magic!
### What about right-to-left (RTL) languages (e.g. Arabic)?
SilverStripe doesn't have built-in support for attribute-based RTL-modifications (`<html dir="rtl">`).
We are currently investigating the available options, and are eager to get feedback on your experiences with translating silverstripe RTL.
### Can I translate/edit the language files in my favourite text editor (on my local installation)
Not for modules managed by transifex.com, including "framework" and "cms.
It causes us a lot of work in merging these files back.
Please use the online translation tool for all new and existing translations.
### How does my translation get into a SilverStripe release?
Currently this is a manual process of a core team member downloading approved translations and committing them into our source tree.
### How does my translation get approved, who is the maintainer?
The online translation tool (transifex.com) is designed to be decentralized and collaborative,
so there's no strict approval or review process.
Every logged-in user on the system can flag translations,
and discuss them with other translators.
### I'm seeing lots of duplicated translations, what should I do?
For now, please translate all duplications - sometimes they might be intentional, but mostly the developer just didn't know his phrase was already translated.
Please contact us about any duplicates that might be worth merging.
### What happened to translate.silverstripe.org?
This was a custom-built online translation tool serving us well for a couple of years,
but started to show its age (performance and maintainability). It was replaced
with transifex.com. All translations from translate.silverstripe.org were migrated.
Unfortunately, the ownership of individual translations couldn't be migrated.
As the new tool doesn't support the PHP format used in SilverStripe 2.x,
this means that we no longer have a working translation tool for PHP files.
Please edit the PHP files directly and [send us pull requests](/misc/contributing).
This also applies for any modules staying compatible with SilverStripe 2.x.
## Contact
Translators have their own [mailinglist](https://groups.google.com/forum/#!forum/silverstripe-translators),
but you can also reach a core member on [IRC](http://silverstripe.org/irc).
The transifex.com interface has a built-in discussion board if
you have specific comments on a translation.
## Related
* [i18n](/topics/i18n): Developer-level documentation of Silverstripe's i18n capabilities
* [translation-process](../translation-process): Information about managing translations for the core team and/or module maintainers.
* [translatable](https://github.com/silverstripe/silverstripe-translatable): DataObject-interface powering the website-content translations
* ["Translatable ModelAdmin" module](http://silverstripe.org/translatablemodeladmin-module/): An extension which allows translations of DataObjects inside ModelAdmin

146
docs/en/05_Contributing/04_Translations.md Normal file
View File

@ -0,0 +1,146 @@
title: Translations
summary: Translate interface components like button labels into multiple languages.
# Contributing Translations
We are always looking for new translators. Even if a specific language already is translated and has an official
maintainer, we can use helping hands in reviewing and updating translations. Important: It is perfectly fine if you
only have time for a partial translation or quick review work - our system accomodates many people collaborating on the
same language.
The content for UI elements (button labels, field titles) and instruction texts shown in the CMS and elsewhere is
stored in the PHP code for a module (see [i18n](/topics/i18n)). All content can be extracted as a "language file", and
uploaded to an online translation editor interface. SilverStripe is already translated in over 60 languages, and we're
relying on native speakers to keep these up to date, and of course add new languages.
Please register a free translator account to get started, even if you just feel like fixing up a few sentences.
## The online translation tool
We provide a GUI for translations through [transifex.com](http://transifex.com). If you don't have an account yet,
please follow the links there to sign up. Select a project from the
[list of translatable modules](https://www.transifex.com/accounts/profile/silverstripe/) and start translating online!
For all modules listed there, we automatically import new master strings as they get committed to the various code
bases (via a nightly task), so you're always translating on the latest and greatest version.
You can check the last successful push of the translation master strings in our
[public continuous integration server](http://teamcity.silverstripe.com/viewType.html?buildTypeId=bt112)
(select "log in as guest").
## FAQ
### What happened to getlocalization.com?
We migrated from getlocalization.com to transifex in mid 2013.
### How do I translate a module not listed on Transifex?
Most modules maintained by SilverStripe are on Transifex. For other modules, have a look in the module README if
there's any specific instructions. If there aren't, you'll need to translate the YAML files directly. If the module is
on github, you can create a fork, edit the files, and send back your pull request all directly on the website
([instructions](https://help.github.com/articles/fork-a-repo)).
### How do I translate substituted strings? (e.g. '%s' or '{my-variable}')
You don't have to - if the english master-string reads 'Hello %s', your german translation would be 'Hallo %s'. Strings
prefixed by a percentage-sign are automatically replaced by silverstripe with dynamic content. See
http://php.net/sprintf for details. The newer `{my-variable}` format works the same way, but makes its intent clearer,
and allows reordering of placeholders in your translation.
### Do I need to convert special characters (e.g. HTML-entities)?
Special characters (such as german umlauts) need to be entered in their native form. Please don't use HTML-entities
("ä" instead of "ä"). Silverstripe stores and renders most strings in UTF8 (Unicode) format.
### How can I check out my translation in the interface?
Currently translated entities are not directly factored into code (for security reasons and release/review-control), so
you can't see them straight away.
It is strongly encouraged that you check your translation this way, as its a good way to double check your translation
works in the right context. Please use our [daily-builds](http://www.silverstripe.org/daily-builds/) for your local
installation, to ensure you're looking at the most up to date interface. See "Download Translations" above to find out
how to retrieve the latest translation files.
### Can I change a translation just for one SilverStripe version?
While we version control our translation files like all other source code, the online translation tool doesn't have the
same capabilities. A translated string (as identified by its unique "entity name") is assumed to work well in all
releases. If the interface changes in a non-trivial fashion, the new translations required should have new identifiers
as well.
Example: We renamed the "Security" menu title to "Users" in our 3.0 release. As it would confuse users of older versions
unnecessarily, we should be using a new entity name for this, and avoid the change propagating to an older SilverStripe
version.
### How do I change my interface language?
Once you've logged into the CMS, you should see the text "Hi <your name>" near the top left, you can click this to edit
your profile ([direct link](http://localhost/admin/myprofile/)). You can then set the "interface language" from a
dropdown which automatically includes all found translations (based on the files in the `/lang` folders).
### I've found a piece of untranslatable text
It is entirely possible that we missed certain strings in preparing Silverstripe for translation-support. If you're
technically minded, please read [i18n](/topics/i18n) on how to make it translatable. Otherwise just post your findings
to the forum.
### How do I add my own module?
Once you've built a translation-enabled module, you can run the "textcollector" on your local installation for this
specific module (see [i18n](/topics/i18n)). This should find all calls to `_t()` in php and template files, and generate
a new lang file with the default locale (path: <mymodule>/lang/en.yml). Upload this file to the online translation
tool, and wait for your translators to do their magic!
### What about right-to-left (RTL) languages (e.g. Arabic)?
SilverStripe doesn't have built-in support for attribute-based RTL-modifications (`<html dir="rtl">`).
We are currently investigating the available options, and are eager to get feedback on your experiences with
translating silverstripe RTL.
### Can I translate/edit the language files in my favorite text editor (on my local installation)
Not for modules managed by transifex.com, including "framework" and "cms. It causes us a lot of work in merging these
files back. Please use the online translation tool for all new and existing translations.
### How does my translation get into a SilverStripe release?
Currently this is a manual process of a core team member downloading approved translations and committing them into our
source tree.
### How does my translation get approved, who is the maintainer?
The online translation tool (transifex.com) is designed to be decentralized and collaborative, so there's no strict
approval or review process. Every logged-in user on the system can flag translations, and discuss them with other
translators.
### I'm seeing lots of duplicated translations, what should I do?
For now, please translate all duplications - sometimes they might be intentional, but mostly the developer just didn't
know his phrase was already translated. Please contact us about any duplicates that might be worth merging.
### What happened to translate.silverstripe.org?
This was a custom-built online translation tool serving us well for a couple of years, but started to show its age
(performance and maintainability). It was replaced with transifex.com. All translations from translate.silverstripe.org
were migrated. Unfortunately, the ownership of individual translations couldn't be migrated.
As the new tool doesn't support the PHP format used in SilverStripe 2.x, this means that we no longer have a working
translation tool for PHP files. Please edit the PHP files directly and [send us pull requests](/misc/contributing).
This also applies for any modules staying compatible with SilverStripe 2.x.
## Contact
Translators have their own [mailinglist](https://groups.google.com/forum/#!forum/silverstripe-translators), but you can
also reach a core member on [IRC](http://silverstripe.org/irc). The transifex.com interface has a built-in discussion
board if you have specific comments on a translation.
## Related
* [i18n](/developer_guids/i18n): Developer-level documentation of Silverstripe's i18n capabilities
* [translation-process](translation-process): Information about managing translations for the core team and/or module maintainers.
* [translatable](https://github.com/silverstripe/silverstripe-translatable): DataObject-interface powering the website-content translations
* ["Translatable ModelAdmin" module](http://silverstripe.org/translatablemodeladmin-module/): An extension which allows translations of DataObjects inside ModelAdmin

104
docs/en/05_Contributing/05_Translation_Process.md
View File

@ -1,55 +1,56 @@
# Translation Process # title: Implement Internationalization
summary: Implement SilverStripe's internationalization system in your own modules.
This page covers a few advanced topics related to SilverStripe's translation system. # Implementing Internationalization
To find out about how to assist with translating SilverStripe, see the [Contributing Translations page](contributing/translation). To find out about how to assist with translating SilverStripe from a users point of view, see the
[Contributing Translations page](translation).
## Set up your own module for localization ## Set up your own module for localization
### Collecting translatable text ### Collecting translatable text
As a first step, you can automatically collect As a first step, you can automatically collect all translatable text in your module through the `i18nTextCollector`
all translatable text in your module through the `i18nTextCollector` task. task. See [i18n](/topics/i18n#collecting-text) for more details.
See [i18n](/topics/i18n#collecting-text) for more details.
### Import master files ### Import master files
If you don't have an account on transifex.com yet, [create a free account now](http://www.transifex.com/signup). If you don't have an account on transifex.com yet, [create a free account now](http://www.transifex.com/signup). After
After creating a new project, you have to upload the `en.yml` master file as a new "Resource". creating a new project, you have to upload the `en.yml` master file as a new "Resource". While you can do this through
While you can do this through the web interface, there's a convenient the web interface, there's a convenient
[commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles) [commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles) for this
for this purpose. In order to use it, set up a new `.tx/config` file in your module folder: purpose. In order to use it, set up a new `.tx/config` file in your module folder:
```yaml
[main]
host = https://www.transifex.com
[main]
host = https://www.transifex.com
[my-project.master] [my-project.master]
file_filter = lang/<lang>.yml file_filter = lang/<lang>.yml
source_file = lang/en.yml source_file = lang/en.yml
source_lang = en source_lang = en
type = YML type = YML
```
If you don't have existing translations, If you don't have existing translations, your project is ready to go - simply point translators to the URL, have them
your project is ready to go - simply point translators sign up, and they can create languages and translations as required.
to the URL, have them sign up, and they can create languages and translations as required.
### Import existing translations ### Import existing translations
In case you have existing translations in YML format, In case you have existing translations in YML format, there's a "New language" option in the web interface.
there's a "New language" option in the web interface.
Alternatively, use the [commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles). Alternatively, use the [commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles).
### Export existing translations ### Export existing translations
You can download new translations in YML format through the web interface, You can download new translations in YML format through the web interface, but that can get quite tedious for more than
but that can get quite tedious for more than a handful of translations. a handful of translations. Again, the [commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles)
Again, the [commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles)
provides a more convenient interface here with the `tx pull` command, downloading all translations as a batch. provides a more convenient interface here with the `tx pull` command, downloading all translations as a batch.
### Merge back existing translations ### Merge back existing translations
If you want to backport translations onto release branches, simply run the `tx pull` command on multiple branches. If you want to backport translations onto release branches, simply run the `tx pull` command on multiple branches. This
This assumes you're adhereing to the following guidelines: assumes you're adhering to the following guidelines:
- For significantly changed content of an entity, create a new entity key - For significantly changed content of an entity, create a new entity key
- For added/removed placeholders, create a new entity - For added/removed placeholders, create a new entity
@ -58,41 +59,48 @@ This assumes you're adhereing to the following guidelines:
### Converting your language files from 2.4 PHP format ### Converting your language files from 2.4 PHP format
The conversion from PHP format to YML is taken care of by a module The conversion from PHP format to YML is taken care of by a module called
called [i18n_yml_converter](https://github.com/chillu/i18n_yml_converter). [i18n_yml_converter](https://github.com/chillu/i18n_yml_converter).
## Download Translations from Transifex.com ## Download Translations from Transifex.com
We are managing our translations through a tool called [transifex.com](http://transifex.com). We are managing our translations through a tool called [transifex.com](http://transifex.com). Most modules are handled
Most modules are handled under the "silverstripe" user, under the "silverstripe" user, see
see [list of translatable modules](https://www.transifex.com/accounts/profile/silverstripe/). [list of translatable modules](https://www.transifex.com/accounts/profile/silverstripe/).
Translations need to be reviewed before being committed, Translations need to be reviewed before being committed, which is a process that happens roughly once per month. We're
which is a process that happens roughly once per month. merging back translations into all supported release branches as well as the `master` branch. The following script
We're merging back translations into all supported release branches as well as the `master` branch. should be applied to the oldest release branch, and then merged forward into newer branches:
The following script should be applied to the oldest release branch, and then merged forward into newer branches:
:::bash
tx pull tx pull
# Manually review changes through git diff, then commit # Manually review changes through git diff, then commit
git add lang/* git add lang/*
git commit -m "Updated translations" git commit -m "Updated translations"
Note: You can download your work right from Transifex in order to speed up the process for your desired language. <div class="notice" markdown="1">
You can download your work right from Transifex in order to speed up the process for your desired language.
</div>
## JavaScript Translations ## JavaScript Translations
SilverStripe also supports translating strings in JavaScript (see [i18n](/topics/i18n)), SilverStripe also supports translating strings in JavaScript (see [i18n](/developer_guides/i18n)), but there's a
but there's a conversion step involved in order to get those translations syncing with Transifex. conversion step involved in order to get those translations syncing with Transifex. Our translation files stored in
Our translation files stored in `mymodule/javascript/lang/*.js` call `ss.i18n.addDictionary()` to add files. `mymodule/javascript/lang/*.js` call `ss.i18n.addDictionary()` to add files.
ss.i18n.addDictionary('de', {"MyNamespace.MyKey": "My Translation"}); :::js
ss.i18n.addDictionary('de', {'MyNamespace.MyKey': 'My Translation'});
But Transifex only accepts structured formats like JSON. But Transifex only accepts structured formats like JSON.
{"MyNamespace.MyKey": "My Translation"} ```
{'MyNamespace.MyKey': 'My Translation'}
```
First of all, you need to create those source files in JSON, and store them in `mymodule/javascript/lang/src/*.js`. In your `.tx/config` you can configure this path as a separate master location. First of all, you need to create those source files in JSON, and store them in `mymodule/javascript/lang/src/*.js`. In your `.tx/config` you can configure this path as a separate master location.
:::ruby
[main] [main]
host = https://www.transifex.com host = https://www.transifex.com
@ -108,9 +116,9 @@ First of all, you need to create those source files in JSON, and store them in `
source_lang = en source_lang = en
type = KEYVALUEJSON type = KEYVALUEJSON
Now you can upload the source files via a normal `tx push`. Once translations come in, Now you can upload the source files via a normal `tx push`. Once translations come in, you need to convert the source
you need to convert the source files back into the JS files SilverStripe can actually read. files back into the JS files SilverStripe can actually read. This requires an installation of our
This requires an installation of our [buildtools](https://github.com/silverstripe/silverstripe-buildtools). [buildtools](https://github.com/silverstripe/silverstripe-buildtools).
tx pull tx pull
(cd .. && phing -Dmodule=mymodule translation-generate-javascript-for-module) (cd .. && phing -Dmodule=mymodule translation-generate-javascript-for-module)

44
docs/en/05_Contributing/index.md
View File

@ -1,39 +1,13 @@
# Contributing title: Contributing
introduction: Any open source product is only as good as the community behind it. You can participate by sharing code, ideas, or simply helping others. No matter what your skill level is, every contribution counts.
Any open source product is only as good as the community behind it. You can ## House rules for everybody contributing to SilverStripe
participate by sharing code, ideas, or simply helping others. No matter what * Ask questions on the [forum](http://silverstripe.org/community/forums), and stick to more high-level discussions on the [core mailinglist](https://groups.google.com/forum/#!forum/silverstripe-dev)
your skill level is, every contribution counts. * Make sure you know how to [raise good bug reports](issues_and_bugs)
* Everybody can contribute to SilverStripe! If you do, ensure you can [submit solid pull requests](code)
See our [high level overview on silverstripe.org](http://silverstripe.org/contributing-to-silverstripe) See our [high level overview on silverstripe.org](http://www.silverstripe.org/community/contributing-to-silverstripe/)
on how you can help out. on how you can help out. Or, for more detailed guidance, read one of the following pages:
Or, for more detailed guidance, read one of the following pages: [CHILDREN]
* [Sharing your **opinion** and raising **issues**](issues)
* [Providing **code**, whether it's creating a feature or fixing a bug](code)
* [Writing and translating **documentation**](documentation)
* [**Translating** user-interface elements](translation)
## House Rules for Everybody
* Ask questions on the [forum](http://silverstripe.org/forum), and stick to more high-level discussions on the [core mailinglist](https://groups.google.com/forum/#!forum/silverstripe-dev)
* Make sure you know how to [raise good bug reports](/misc/contributing/issues)
* Everybody can contribute to SilverStripe! If you do, ensure you can [submit solid pull requests](/misc/contributing/code)
## House Rules for the Core Team
The "core team" consists of everybody with write permissions to our codebase.
With great power comes great responsibility, so we have agreed on certain expectations:
* Be friendly, encouraging and constructive towards other community members
* Frequently review pull requests and new issues (in particular, respond quickly to @mentions)
* Treat issues according to our [issue guidelines](/misc/contributing/issues)
* Don't commit directly to core, raise pull requests instead (except trivial fixes)
* Only merge code you have tested and fully understand. If in doubt, ask for a second opinion.
* Ensure contributions have appropriate [test coverage](/topics/testing), are documented, and pass our [coding conventions](/misc/coding-conventions)
* Keep the codebase "releasable" at all times (check our [release process](/misc/release-process))
* API changes and non-trivial features should not be merged into release branches.
* API changes on master should not be merged until they have the buy-in of at least two core committers (or better, through the [core mailinglist](https://groups.google.com/forum/#!forum/silverstripe-dev))
* Be inclusive. Ensure a wide range of SilverStripe developers can obtain an understanding of your code and docs, and you're not the only one who can maintain it.
* Avoid `git push --force`, and be careful with your git remotes (no accidental pushes)
* Use your own forks to create feature branches