From Fedora Project Wiki

([syntax coloration] vim tips added for helping marking string as translatable)
No edit summary
(19 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{autolang|base=yes}}
{{header|websites}}
This page describes how to fix a bug or submit other changes to the Fedora Project website.  Anyone can perform these steps, and you do not need special permission to send a patch to the {{fplist|websites}} list for consideration.
This page describes how to fix a bug or submit other changes to the Fedora Project website.  Anyone can perform these steps, and you do not need special permission to send a patch to the {{fplist|websites}} list for consideration.


Line 16: Line 19:
<li>Set up at least your name and email address in your global ''git'' configuration, as shown on [[Git_quick_reference#Configure_your_global_git_settings|this section]] of the git quick reference.</li>
<li>Set up at least your name and email address in your global ''git'' configuration, as shown on [[Git_quick_reference#Configure_your_global_git_settings|this section]] of the git quick reference.</li>


<li>Make sure you are in a directory to which you have write access, such as your home directory or a subdirectory, and clone the websites repository.  ''This takes several minutes on a fast connection.''
<li>Make sure you are in a directory to which you have write access, such as your home directory or a subdirectory, and clone the websites repository.  ''This takes several minutes on a fast connection.'' '''hint:''' use <code>--depth 1</code> in order to download the latest revision only, as the repo has plenty of pictures on the history and is heavy. Do so by removing the dash ("#") from the bellow command.
<pre>cd $HOME
<pre>cd $HOME
git clone git://git.fedorahosted.org/git/fedora-web.git</pre></li>
git clone git://git.fedorahosted.org/git/fedora-web.git #--depth 1</pre></li>


<li>Change directory to the website you want to change.  The repository carries several sites, including fedoraproject.org, spins.fedoraproject.org, and others.
<li>Change directory to the website you want to change.  The repository carries several sites, including fedoraproject.org, spins.fedoraproject.org, and others.
Line 31: Line 34:


<li>Test your changes.
<li>Test your changes.
<pre>make</pre>
<pre>make</pre>
After the make completes successfully and the website will now be available in your /out/ directory.
After the make completes successfully and the website will now be available in your /out/ directory.
Line 64: Line 68:
Instructions for using your fedorapeople.org space are found on the [[fedorapeople.org|fedorapeople.org wiki page]].
Instructions for using your fedorapeople.org space are found on the [[fedorapeople.org|fedorapeople.org wiki page]].


== Editing html file for L10n ==
== Making text translatable ==
Strings which have to be translated should be surrounded by ''${_('str')}'' or ''${Markup(_('str'))}'' if it contains url.  
Text intended for a human reader should be made into ''translatable strings''. Text to be translated should be surrounded by one of the following:
In order to highlight them you can add a vim specific color syntax. Just do as following:
* If the string contains other HTML markup such as special characters (such as &lt; &gt; found in HTML markup), surround the string like this: <pre>${Markup(_('str'))}</pre>
* If there is no such special markup or characters, surround the string like this: <pre>${_('str')}</pre>
 
In some cases, you may want a piece of text to be changeable without disturbing the rest of the translation. This is often the case with quantities that might change from release to release such as a file size.  Here is an example of using named substitution to accomplish this goal:
<pre>${_('%(size)s, DVD ISO disc image for %(arch)s-bit PC') % {'size':'3.1 GB', 'arch':'32'}}</pre>
 
Many editors will automatically highlight this syntax.  Others such as vim can be customized to do so. To add a vim specific color syntax, run the following:
<pre>vi ~/.vim/after/syntax/html.vim</pre>
<pre>vi ~/.vim/after/syntax/html.vim</pre>
Then, insert bellow code in this new file
Then, insert the code below into this new file.
<pre>
<pre>
" highlight Comment ctermfg=Green guifg=Green
" highlight Comment ctermfg=Green guifg=Green
   syn region htmlComment    start=+${_('+          end=+')}+
   sy  match  htmlComment    /${_(["'].*["'])}/
   syn region htmlComment    start=+${_("+          end=+")}+
   sy  match  htmlComment    /${Markup(_(["'].*["']))}
  syn region htmlComment    start=+${Markup(_('+    end=+'))}+
 
  syn region htmlComment    start=+${Markup(_("+    end=+"))}+
" error highlighted
" error highlighted
   sy match htmlComment  /${_([0-9A-Za-z%].*')}/ contains=htmlCommentError
   sy match htmlComment  /${_([0-9A-Za-z%].*')}/ contains=htmlCommentError
Line 80: Line 89:
</pre>
</pre>


This code is given as an example, feel free to improve it. For each html file, vim will overight default color by the comment  
This code is an example, and somewhat incomplete -- feel free to improve it and edit this page. For each HTML file, vim will override the default color with the comment color of the right strings, and highlight strings that have errors.
color of the right strings, and highlight strings that have errors. It is not complete, but helps nevertheless.
 
== FAQ ==
 
=== How do I avoid changing strings when I commit/push? ===
 
After you create your changes to an HTML file and run ''make'', the POT and PO files are updated automatically.  If you are working during a time when strings are supposed to be frozen for translators, you may not want to push these string changes out.  Here's how to avoid that problem:
* Use ''git add &lt;filename&gt;'' and ''git commit -m 'commit message''' to commit your HTML changes.  Remember to make these changes meaningful.  ''Do not use ''git add .'' if you've made lots of unrelated changes; it's a bad habit.''
* Repeat previous step as often as needed to commit all changes.
* Run ''git stash'' to stash the other changes you've made.
* (Optional/Recommended?) Run ''git pull --rebase'' to make sure you've got the latest changes from upstream and that your changes don't cause any weird conflicts.
* Run ''git push origin &lt;branch-name&gt;'' to push your HTML changes out.
* Run ''git stash pop'' to bring your other changes back to the working tree, and off the stack of stashes.
 
=== How do I push my changes once I've become a member of the websites team? ===
 
If you've been bitten by the bug-fixing bug and are contributing on a regular basis, you'll want to update your git settings to push directly to the git repository.  To do so, run ''git remote set-url origin ssh://git.fedorahosted.org/git/fedora-web.git'' in your local fedora-web repository.


== Additional information ==
== Additional information ==

Revision as of 20:37, 27 October 2013


This page describes how to fix a bug or submit other changes to the Fedora Project website. Anyone can perform these steps, and you do not need special permission to send a patch to the websites list for consideration.

Making changes

Important.png
Never use root account for this
Do not use your system's root account for this work. All of these steps can be run by a normal user. You only need to provide the root password to install packages in the first step.

This procedure shows you how to copy the fedora-web repository locally and use your local store to make changes.

  1. Ensure you have the Package-x-generic-16.pnggit package and the Apache web server installed:
    su -c 'yum shell'
    > install git gettext python-genshi python-setuptools babel python-feedparser
    > groupinstall 'Web Server'
    > run
  2. Set up at least your name and email address in your global git configuration, as shown on this section of the git quick reference.
  3. Make sure you are in a directory to which you have write access, such as your home directory or a subdirectory, and clone the websites repository. This takes several minutes on a fast connection. hint: use --depth 1 in order to download the latest revision only, as the repo has plenty of pictures on the history and is heavy. Do so by removing the dash ("#") from the bellow command.
    cd $HOME
    git clone git://git.fedorahosted.org/git/fedora-web.git #--depth 1
  4. Change directory to the website you want to change. The repository carries several sites, including fedoraproject.org, spins.fedoraproject.org, and others.
    cd fedora-web/fedoraproject.org
  5. You can make a fresh, new branch for your changes, or you can do your work against an existing branch of the fedora-web project. To make a fresh branch for your own use only ("mychanges" is a name you can choose):
    git checkout -b mychanges

    If you want to work on something that already exists as a branch on websites, like a redesign branch, you can set up your branch to track the changes on that branch. That allows you to build on the existing work without worrying about whether you're overwriting the existing team's work. For example, if you want to help with the "fpo-redesign" branch:

    git checkout -b mychanges --track origin/fpo-redesign
  6. Make your changes. It's best to make a set of related changes together, but don't make many unrelated changes at once. For instance, it's OK to make several spelling fixes together, but don't combine those with an additional navigation menu option.
  7. Test your changes.
    make

    After the make completes successfully and the website will now be available in your /out/ directory. Now run a local sandbox test of the website:

    make test
  8. Point your web browser at http://localhost:5000 to view the sandbox site. When you are done viewing, stop the temporary web server:
    make stoptest
  9. If everything looks OK, stage the files you changed:
    git add data/content/file1.html data/content/file2.html
  10. Commit the staged changes:
    git commit -m 'Fix spelling errors'

Sending in your changes

  1. When you're done, create patch files for your changes:
    git format-patch origin/master
  2. Now you can send the patches you've created, which will have names such as 0001-my-change.patch, to the websites list.
Note.png
Sending a test patch
If you want to send a test patch somewhere, please don't use the websites list. Instead, send to your own @fedoraproject.org email. Thank you!

Showing off your changes

You can copy the contents of the /out/ folder to a web share, if you have one, for viewing. Your fedorapeople.org space provides this under the ~/public_html/ folder.

ADVANCED USERS: You can also copy your git tree to your fedorapeople.org storage site, which allows us to easily pull them in. If you don't have a fedorapeople.org account, you'll need to post your changes somewhere and let us know.

Instructions for using your fedorapeople.org space are found on the fedorapeople.org wiki page.

Making text translatable

Text intended for a human reader should be made into translatable strings. Text to be translated should be surrounded by one of the following:

  • If the string contains other HTML markup such as special characters (such as < > found in HTML markup), surround the string like this:
    ${Markup(_('str'))}
  • If there is no such special markup or characters, surround the string like this:
    ${_('str')}

In some cases, you may want a piece of text to be changeable without disturbing the rest of the translation. This is often the case with quantities that might change from release to release such as a file size. Here is an example of using named substitution to accomplish this goal:

${_('%(size)s, DVD ISO disc image for %(arch)s-bit PC') % {'size':'3.1 GB', 'arch':'32'}}

Many editors will automatically highlight this syntax. Others such as vim can be customized to do so. To add a vim specific color syntax, run the following:

vi ~/.vim/after/syntax/html.vim

Then, insert the code below into this new file.

" highlight Comment ctermfg=Green guifg=Green
  sy  match  htmlComment    /${_(["'].*["'])}/
  sy  match  htmlComment    /${Markup(_(["'].*["']))}/   

" error highlighted
  sy match htmlComment  /${_([0-9A-Za-z%].*')}/ contains=htmlCommentError
  sy match htmlComment  /${Markup((.*[)]{,1}}/  contains=htmlCommentError

This code is an example, and somewhat incomplete -- feel free to improve it and edit this page. For each HTML file, vim will override the default color with the comment color of the right strings, and highlight strings that have errors.

FAQ

How do I avoid changing strings when I commit/push?

After you create your changes to an HTML file and run make, the POT and PO files are updated automatically. If you are working during a time when strings are supposed to be frozen for translators, you may not want to push these string changes out. Here's how to avoid that problem:

  • Use git add <filename> and git commit -m 'commit message' to commit your HTML changes. Remember to make these changes meaningful. Do not use git add . if you've made lots of unrelated changes; it's a bad habit.
  • Repeat previous step as often as needed to commit all changes.
  • Run git stash to stash the other changes you've made.
  • (Optional/Recommended?) Run git pull --rebase to make sure you've got the latest changes from upstream and that your changes don't cause any weird conflicts.
  • Run git push origin <branch-name> to push your HTML changes out.
  • Run git stash pop to bring your other changes back to the working tree, and off the stack of stashes.

How do I push my changes once I've become a member of the websites team?

If you've been bitten by the bug-fixing bug and are contributing on a regular basis, you'll want to update your git settings to push directly to the git repository. To do so, run git remote set-url origin ssh://git.fedorahosted.org/git/fedora-web.git in your local fedora-web repository.

Additional information

The git quick reference might be useful for you, beyond just setting up your global configuration.

The Git Community Book is an excellent reference if you find git useful and want to learn more about it.

You don't have to be a member of the Websites team to help fix things on the site, but if you find yourself doing it more than once, you might want to join us!