mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-07-01 00:49:33 +02:00
Review and tidy up contributing documentation.
This commit is contained in:
Will Rossiter
Cam Findlay
parent
d52b475cfb
commit
80d4127f43
|
|
@ -1,3 +1,6 @@
|
|||
title: Bug Reports
|
||||
summary: Report bugs or problems with SilverStripe, feature requests or other issues.
|
||||
|
||||
# Contributing Issues and Opinions
|
||||
|
||||
## Reporting Bugs
|
||||
|
|
@ -29,26 +32,31 @@ If the issue does look like a new bug:
|
|||
* Describe your environment as detailed as possible: SilverStripe version, Browser, PHP version, Operating System, any installed SilverStripe modules.
|
||||
* *(optional)* [Submit a pull request](/misc/contributing/code) which fixes the issue.
|
||||
|
||||
Lastly, don't get your hopes up too high. Unless your issue is a blocker affecting a large
|
||||
number of users, don't expect SilverStripe developers to jump onto it right way.
|
||||
Your issue is a starting point where others with the same problem can collaborate
|
||||
with you to develop a fix.
|
||||
Lastly, don't get your hopes up too high. Unless your issue is a blocker
|
||||
affecting a large number of users, don't expect SilverStripe developers to jump
|
||||
onto it right way. Your issue is a starting point where others with the same
|
||||
problem can collaborate with you to develop a fix.
|
||||
|
||||
## Feature Requests
|
||||
|
||||
<div class="warning" markdown='1'>
|
||||
Please don't file "feature requests" as issues. If there's a new feature you'd like to see
|
||||
in SilverStripe, you either need to write it yourself (and [submit a pull request](/misc/contributing/code))
|
||||
or convince somebody else to write it for you. Any "wishlist" type issues without code attached
|
||||
can be expected to be closed as soon as they're reviewed.
|
||||
Please don't file "feature requests" as Github issues. If there's a new feature
|
||||
you'd like to see in SilverStripe, you either need to write it yourself (and
|
||||
[submit a pull request](/misc/contributing/code)) or convince somebody else to
|
||||
write it for you. Any "wishlist" type issues without code attached can be
|
||||
expected to be closed as soon as they're reviewed.
|
||||
</div>
|
||||
|
||||
In order to gain interest and feedback in your feature, we encourage you to 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).
|
||||
In order to gain interest and feedback in your feature, we encourage you to
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
summary: Describes the process followed for "core" releases.
|
||||
|
||||
# Release Process
|
||||
|
||||
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 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.
|
||||
|
||||
### 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.
|
||||
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!
|
||||
* The commit message should contain an `API` prefix (see ["commit message format"](/misc/contributing/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.
|
||||
* 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.
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -143,7 +146,8 @@ webserver access logs (if a hack is suspected), any other services and web packa
|
|||
|
||||
### 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 |
|
||||
|---------------|-------------|
|
||||
|
|
|
|||
|
|
@ -1,109 +1,97 @@
|
|||
title: Documentation
|
||||
summary: Developer and CMS User Help 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,
|
||||
we encourage everybody to contribute, from simply fixing spelling mistakes, to writing recipes/howtos,
|
||||
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.
|
||||
Modifying documentation requires basic [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) and
|
||||
[Markdown](http://daringfireball.net/projects/markdown/) knowledge, and a GitHub user account.
|
||||
|
||||
## Editing online
|
||||
|
||||
The easiest way of making a change to the documentation is by clicking the "Edit this page" link at
|
||||
the bottom of the page you want to edit. Alternativly, you can find the appropriate .md file in
|
||||
the [github.com/silverstripe/silverstripe-framework](https://github.com/silverstripe/silverstripe-framework/tree/3.0/docs/) repository
|
||||
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.
|
||||
The easiest way of making a change to the documentation is by clicking the "Edit this page" link at the bottom of the
|
||||
page you want to edit. Alternativly, you can find the appropriate .md file in the
|
||||
[github.com/silverstripe/silverstripe-framework](https://github.com/silverstripe/silverstripe-framework/tree/master/docs/)
|
||||
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
|
||||
|
||||
If you prefer to edit the content on your local machine, you can "[fork](http://help.github.com/forking/)"
|
||||
the [github.com/silverstripe/silverstripe-framework](http://github.com/silverstripe/silverstripe-framework)
|
||||
and [github.com/silverstripe/silverstripe-cms](http://github.com/silverstripe/silverstripe-cms)
|
||||
repositories and send us "[pull requests](http://help.github.com/pull-requests/)". If you have
|
||||
downloaded SilverStripe or a module, chances are that you already have these checkouts.
|
||||
If you prefer to edit the content on your local machine, you can "[fork](http://help.github.com/forking/)" the
|
||||
[github.com/silverstripe/silverstripe-framework](http://github.com/silverstripe/silverstripe-framework) and
|
||||
[github.com/silverstripe/silverstripe-cms](http://github.com/silverstripe/silverstripe-cms) repositories and send us
|
||||
"[pull requests](http://help.github.com/pull-requests/)". If you have downloaded SilverStripe or a module, chances are
|
||||
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
|
||||
includes updates to the necessary documentation. This helps prevent our documentation from
|
||||
getting out of date.
|
||||
<div class="warning" markdown='1'>
|
||||
If you submit a new feature or an API change, we strongly recommend that your patch includes updates to the necessary
|
||||
documentation. This helps prevent our documentation from getting out of date.
|
||||
</div>
|
||||
|
||||
## Repositories
|
||||
|
||||
* End-user: [userhelp.silverstripe.org](http://userhelp.silverstripe.org) - a custom SilverStripe project (not open sourced at the moment).
|
||||
* Developer Guides: [doc.silverstripe.org](http://doc.silverstripe.org) - powered by a
|
||||
SilverStripe project that uses the ["docsviewer" module](https://github.com/silverstripe/silverstripe-docsviewer)
|
||||
to convert Markdown formatted files into searchable HTML pages with index lists.
|
||||
Its contents are fetched from different releases automatically every couple of minutes.
|
||||
* Developer API Docuumentation: [api.silverstripe.org](http://api.silverstripe.org) - powered by a customized
|
||||
[phpDocumentor](http://www.phpdoc.org/) template, and is regenerated automatically every night.
|
||||
* End-user: [userhelp.silverstripe.org](http://userhelp.silverstripe.org).
|
||||
* Developer Guides: [doc.silverstripe.org](http://doc.silverstripe.org).
|
||||
* Developer API Docuumentation: [api.silverstripe.org](http://api.silverstripe.org).
|
||||
|
||||
## Source Control
|
||||
|
||||
In order to balance editorial control with effective collaboration, we keep
|
||||
documentation alongside the module source code, e.g. in `framework/docs/`,
|
||||
or as code comments within PHP code.
|
||||
Contributing documentation is the same process as providing any other patch
|
||||
(see [Contributing code](code)).
|
||||
In order to balance editorial control with effective collaboration, we keep documentation alongside the module source
|
||||
code, e.g. in `framework/docs/`, or as code comments within PHP code. Contributing documentation is the same process as
|
||||
providing any other patch (see [Contributing code](code)).
|
||||
|
||||
## 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
|
||||
introduction to the different types of documentation, and [Producing OSS: "Documentation"](http://producingoss.com/en/getting-started.html#documentation)
|
||||
for good rules of thumb for documenting opensource software.
|
||||
introduction to the different types of documentation, and
|
||||
[Producing OSS: "Documentation"](http://producingoss.com/en/getting-started.html#documentation) for good rules of thumb
|
||||
for documenting open source software.
|
||||
|
||||
## 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
|
||||
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 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 sourcecode (API and Developer Guides) are valueable ressources.
|
||||
* API and Developer Guides complement each other: Both forms of documenting source code (API and Developer Guides) are valuable resources.
|
||||
* 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
|
||||
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`).
|
||||
* 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
|
||||
|
||||
* 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.
|
||||
* Write in an active and direct voice
|
||||
* 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.
|
||||
* 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
|
||||
|
||||
There are several built-in block styles for highlighting a paragraph of text.
|
||||
Please use these graphical elements sparingly.
|
||||
There are several built-in block styles for highlighting a paragraph of text. Please use these graphical elements
|
||||
sparingly.
|
||||
|
||||
<div class="hint" markdown='1'>
|
||||
"Tip box": Adds, deepens or accents information in the main text.
|
||||
Can be used for background knowledge, or "see also" links.
|
||||
"Tip box": Adds, deepens or accents information in the main text. Can be used for background knowledge, or "see also"
|
||||
links.
|
||||
</div>
|
||||
|
||||
Code:
|
||||
|
|
@ -113,8 +101,8 @@ Code:
|
|||
</div>
|
||||
|
||||
<div class="notice" markdown='1'>
|
||||
"Notification box": Technical notifications relating to the main text.
|
||||
For example, notifying users about a deprecated feature.
|
||||
"Notification box": Technical notifications relating to the main text. For example, notifying users about a deprecated
|
||||
feature.
|
||||
</div>
|
||||
|
||||
Code:
|
||||
|
|
@ -124,9 +112,8 @@ Code:
|
|||
</div>
|
||||
|
||||
<div class="warning" markdown='1'>
|
||||
"Warning box": Highlight a severe bug or technical issue requiring
|
||||
a users attention. For example, a code block with destructive functionality
|
||||
might not have its URL actions secured to keep the code shorter.
|
||||
"Warning box": Highlight a severe bug or technical issue requiring a users attention. For example, a code block with
|
||||
destructive functionality might not have its URL actions secured to keep the code shorter.
|
||||
</div>
|
||||
|
||||
Code:
|
||||
|
|
@ -140,10 +127,10 @@ on placing HTML blocks inside Markdown.
|
|||
|
||||
## Translating Documentation
|
||||
|
||||
Documentation is kept alongside the source code, typically in a module subdirectory like `framework/docs/en/`.
|
||||
Each language has its own subfolder, which can duplicate parts or the whole body of documentation.
|
||||
German documentation would for example live in `framework/docs/de/`.
|
||||
The [docsviewer](https://github.com/silverstripe/silverstripe-docsviewer) module that drives
|
||||
Documentation is kept alongside the source code, typically in a module subdirectory like `framework/docs/en/`. Each
|
||||
language has its own subfolder, which can duplicate parts or the whole body of documentation. German documentation
|
||||
would for example live in `framework/docs/de/`. The
|
||||
[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.
|
||||
|
||||
## Further reading
|
||||
|
|
|
|||
|
|
@ -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 ("ä" 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
146
docs/en/05_Contributing/04_Translations.md
Normal 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
|
||||
|
|
@ -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
|
||||
|
||||
### Collecting translatable text
|
||||
|
||||
As a first step, you can automatically collect
|
||||
all translatable text in your module through the `i18nTextCollector` task.
|
||||
See [i18n](/topics/i18n#collecting-text) for more details.
|
||||
As a first step, you can automatically collect all translatable text in your module through the `i18nTextCollector`
|
||||
task. See [i18n](/topics/i18n#collecting-text) for more details.
|
||||
|
||||
### Import master files
|
||||
|
||||
If you don't have an account on transifex.com yet, [create a free account now](http://www.transifex.com/signup).
|
||||
After creating a new project, you have to upload the `en.yml` master file as a new "Resource".
|
||||
While you can do this through the web interface, there's a convenient
|
||||
[commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles)
|
||||
for this purpose. In order to use it, set up a new `.tx/config` file in your module folder:
|
||||
If you don't have an account on transifex.com yet, [create a free account now](http://www.transifex.com/signup). After
|
||||
creating a new project, you have to upload the `en.yml` master file as a new "Resource". While you can do this through
|
||||
the web interface, there's a convenient
|
||||
[commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles) for this
|
||||
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]
|
||||
file_filter = lang/<lang>.yml
|
||||
source_file = lang/en.yml
|
||||
source_lang = en
|
||||
type = YML
|
||||
[my-project.master]
|
||||
file_filter = lang/<lang>.yml
|
||||
source_file = lang/en.yml
|
||||
source_lang = en
|
||||
type = YML
|
||||
```
|
||||
|
||||
If you don't have existing translations,
|
||||
your project is ready to go - simply point translators
|
||||
to the URL, have them sign up, and they can create languages and translations as required.
|
||||
If you don't have existing translations, your project is ready to go - simply point translators to the URL, have them
|
||||
sign up, and they can create languages and translations as required.
|
||||
|
||||
### Import existing translations
|
||||
|
||||
In case you have existing translations in YML format,
|
||||
there's a "New language" option in the web interface.
|
||||
In case you have existing translations in YML format, 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).
|
||||
|
||||
### Export existing translations
|
||||
|
||||
You can download new translations in YML format through the web interface,
|
||||
but that can get quite tedious for more than a handful of translations.
|
||||
Again, the [commandline client](http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles)
|
||||
You can download new translations in YML format through the web interface, but that can get quite tedious for more than
|
||||
a handful of translations. 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.
|
||||
|
||||
### Merge back existing translations
|
||||
|
||||
If you want to backport translations onto release branches, simply run the `tx pull` command on multiple branches.
|
||||
This assumes you're adhereing to the following guidelines:
|
||||
If you want to backport translations onto release branches, simply run the `tx pull` command on multiple branches. This
|
||||
assumes you're adhering to the following guidelines:
|
||||
|
||||
- For significantly changed content of an entity, create a new entity key
|
||||
- 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
|
||||
|
||||
The conversion from PHP format to YML is taken care of by a module
|
||||
called [i18n_yml_converter](https://github.com/chillu/i18n_yml_converter).
|
||||
The conversion from PHP format to YML is taken care of by a module called
|
||||
[i18n_yml_converter](https://github.com/chillu/i18n_yml_converter).
|
||||
|
||||
## Download Translations from Transifex.com
|
||||
|
||||
We are managing our translations through a tool called [transifex.com](http://transifex.com).
|
||||
Most modules are handled under the "silverstripe" user,
|
||||
see [list of translatable modules](https://www.transifex.com/accounts/profile/silverstripe/).
|
||||
We are managing our translations through a tool called [transifex.com](http://transifex.com). Most modules are handled
|
||||
under the "silverstripe" user, see
|
||||
[list of translatable modules](https://www.transifex.com/accounts/profile/silverstripe/).
|
||||
|
||||
Translations need to be reviewed before being committed,
|
||||
which is a process that happens roughly once per month.
|
||||
We're merging back translations into all supported release branches as well as the `master` branch.
|
||||
The following script should be applied to the oldest release branch, and then merged forward into newer branches:
|
||||
Translations need to be reviewed before being committed, which is a process that happens roughly once per month. We're
|
||||
merging back translations into all supported release branches as well as the `master` branch. The following script
|
||||
should be applied to the oldest release branch, and then merged forward into newer branches:
|
||||
|
||||
:::bash
|
||||
tx pull
|
||||
|
||||
# Manually review changes through git diff, then commit
|
||||
git add lang/*
|
||||
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
|
||||
|
||||
SilverStripe also supports translating strings in JavaScript (see [i18n](/topics/i18n)),
|
||||
but there's a conversion step involved in order to get those translations syncing with Transifex.
|
||||
Our translation files stored in `mymodule/javascript/lang/*.js` call `ss.i18n.addDictionary()` to add files.
|
||||
|
||||
ss.i18n.addDictionary('de', {"MyNamespace.MyKey": "My Translation"});
|
||||
SilverStripe also supports translating strings in JavaScript (see [i18n](/developer_guides/i18n)), but there's a
|
||||
conversion step involved in order to get those translations syncing with Transifex. Our translation files stored in
|
||||
`mymodule/javascript/lang/*.js` call `ss.i18n.addDictionary()` to add files.
|
||||
|
||||
:::js
|
||||
ss.i18n.addDictionary('de', {'MyNamespace.MyKey': 'My Translation'});
|
||||
|
||||
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.
|
||||
|
||||
|
||||
:::ruby
|
||||
[main]
|
||||
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
|
||||
type = KEYVALUEJSON
|
||||
|
||||
Now you can upload the source files via a normal `tx push`. Once translations come in,
|
||||
you need to convert the source files back into the JS files SilverStripe can actually read.
|
||||
This requires an installation of our [buildtools](https://github.com/silverstripe/silverstripe-buildtools).
|
||||
Now you can upload the source files via a normal `tx push`. Once translations come in, you need to convert the source
|
||||
files back into the JS files SilverStripe can actually read. This requires an installation of our
|
||||
[buildtools](https://github.com/silverstripe/silverstripe-buildtools).
|
||||
|
||||
tx pull
|
||||
(cd .. && phing -Dmodule=mymodule translation-generate-javascript-for-module)
|
||||
|
|
|
|||
|
|
@ -1,20 +1,13 @@
|
|||
# Contributing
|
||||
|
||||
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.
|
||||
|
||||
See our [high level overview on silverstripe.org](http://silverstripe.org/contributing-to-silverstripe)
|
||||
on how you can help out.
|
||||
|
||||
Or, for more detailed guidance, read one of the following pages:
|
||||
|
||||
* [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)
|
||||
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.
|
||||
|
||||
## House rules for everybody contributing to SilverStripe
|
||||
* 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)
|
||||
* 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)
|
||||
* 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://www.silverstripe.org/community/contributing-to-silverstripe/)
|
||||
on how you can help out. Or, for more detailed guidance, read one of the following pages:
|
||||
|
||||
[CHILDREN]
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user