The W3C Internationalization Activity uses github for document development. This page provides guidelines to help people contribute content that matches the standard styling and keeps the documents in a state that keeps the publication process straightforward.
If you have comments or suggestions about how to improve this page, feel free to raise a Github issue.
See also the guidelines for working with github.
You should always bear in mind the following when creating content:
lang attribute in the html tag. A range of text in another language inside the document should be tagged for language too, using the lang attribute.dir attribute.We recommend adding the standard i18n CSS rules in a file called local.css. These rules can be found below.
Important: Only make minimal changes to the source code. If you commit an update that has lots of formatting changes in the source code, it obscures the actual substantive changes in the github diff. You must use an editor that doesn't automatically re-layout the source text each time you make changes. If you do want to tidy the source text, do so as a separate commit, with no substantive changes applied, and describe the commit so that people are aware that it is just a source tidy.
Put pictures, tables, examples, and the like in figure markup. Use the figcaption element when you want a caption. (Caption use is encouraged.)
To refer to a figure from the text, just use an empty a element, with href pointing to the id of the figure element, eg. <a href="#figure_id"></a>. Respec will automatically add the figure number to the link text when the page is displayed.
To create a block-type note add class="note" to the paragraph if a single para note, or use a div class="note" around the note if it contains multiple paras or blocks.
For editor's notes, put class="issue" on a p, div or span around the text you want to be the editor's note.
Do not supply numbering for section headings. These will be provided automatically by respec.
An h1..h6 element should be used for headings, and should always be a direct child of a section element. The section element should have an id.
Surround the text of the heading with a link to the id in the section tag, to make it easier to find the id.
<section id="mylinkid"> <h3><a href="#mylinkid">My header text</a></h3> ... </section>
The current styling for TR documents makes it often difficult to quickly find section headings. Use the styling suggested below in your local.css file in order to open up the space between sections.
To refer to a section from the text, just use an empty a element, with href pointing to the id of the section element, eg. <a href="#section_id"></a>. Respec will automatically add the section number and heading to the link text when the page is displayed.
Sometimes it's not necessary to create a new section and heading, but you may want to highlight a word or sentence at the start of a series of paragraphs. To do this, use the following markup.
<span class="leadin">highlighted text goes here</span> Rest of paragraph follows...
Use the abbr element for both of these. Spell out the full form in the title attribute.
A colon should be used for a sentence that leads into the list.
If a list is expressed as a single sentence each list item should begin with a lower case letter and end with a comma or ", and". The last list item should end with a full stop.
Example:
Every W3C specification MUST:
Otherwise, each list element should begin with an uppercase letter and end with a full stop.
Example
Some aspects of Unicode that require additional specification for the Web include:
To show changes to the text use ins and del. However, remember that if you do commits carefully, such markup is not needed. People will be able to see the changes by looking at the diff for the commit on the Github site.
The following table suggests conventions for marking up inline content. The presentation column applies to the English version. Any translated version may change the presentation (eg. a Japanese version may substitute underlining for bold).
| Type of in-line content | Example | Markup to use |
|---|---|---|
| emphasis (general) | In keyboard input it is not always the case that... | em |
| emphasis (stronger) | you must absolutely not do that! | strong |
| new term introduction | The set of characters is called a repertoire. | dfn id="def_<termName>" title="<termName>" |
| reference to a term definition | The repertoire of UTF-8 includes all characters you're likely to need. | a class="termref" href="#def_<termName>" |
| document title | see Requirements for String Identity Matching. | cite |
| quoted term | The word character is used in many contexts. | span class="qterm" |
| quoted term / phrase expressing dubious usage | ie. numeric positions within a string | span class="quote" |
| quoted text | such as ...as it may from time to time be revised or amended. |
q |
| quoted character (refers to typically one, but occasionally more, specific characters). | The character ç is common in French. | span class="qchar" |
| quoted sample output (cf. HTML SAMP) | The string artículo is subject to different representations | samp |
| quoted code | sucçon |
code translate="no" |
| quoted keyboard input (cf. HTML KBD) | a user typing çé on a traditional French-Canadian keyboard | kbd |
| element name | a user agent that looks for artículo elements |
span class="el" translate="no" |
| attribute name or value | the section element |
code class="kw" translate="no" |
| function name | The doit function returns interesting results. |
code class="kw" translate="no" |
| key word in a markup or programming language | the IANA charset value |
code class="kw" translate="no" |
| variable name | var | |
| conformance related word based on rfc2119 | All references to Unicode MUST refer to... | span class="rfc2119" |
| acronyms & abbreviations | More and more APIs are defined, | abbr title="..." |
| Unicode name | Use U+0338 COMBINING LONG SOLIDUS OVERLAY for that. | span class="uname" |
| an URL that doesn't have a link on it | https://github.com/w3c/repoName/ | <span class="url">https://github.com/w3c/repoName/</span> |
If you use b or i tags, use a class name with them, so that semantically different
usages can be styled differently (esp. for documents with
translations!).
The following styles can be used as the base for the local.css file. They contain style rules for the approaches mentioned in this styleguide.
h2 {
margin-top: 3em;
margin-bottom: 0em;
}
.head h2, #abstract h2, #sotd h2 {
margin-top: 0;
}
h3 {
margin-top: 3em;
}
h4 {
font-size: 100%;
font-weight: normal;
color: #005a9c;
margin-top: 2em;
}
.leadin {
font-weight: bold;
}
ins {
background-color: #99FF99;
text-decoration: none;
}
del {
display: inline;
color: silver;
}
figure {
margin-bottom: 2em;
text-align: center;
}
figcaption {
text-align: center;
margin: 0.5em 2em;
font-style: italic;
font-size: 90%;
}
.figno:after {
content: ':\00A0 ';
}
a.termref:link {
color:#C60;
text-decoration:none;
border-bottom: 1px dotted #FC0;
}
a.termref:hover {
color:#C60;
text-decoration:none;
border-bottom: 1px dotted #FC0;
}
a.termref:visited {
color:#C60;
text-decoration:none;
border-bottom: 1px dotted #FC0;
}
a.termref:active {
color:#C60;
text-decoration:none;
border-bottom: 1px dotted #FC0;
}
.qterm:before, .qchar:before { content: "'"; }
.qterm:after, .qchar:after { content: "'"; }
.quote:before { content: '"'; }
.quote:after { content: '"'; }
code {
color: #A52A2A;
font-family: Consolas, "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", Monaco, "Courier New", monospace;
font-size: 100%;
}
samp, kbd {
font-family: Consolas, "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", Monaco, "Courier New", monospace;
font-size: 100%;
}
.uname {
text-transform: uppercase;
font-size: 85%;
letter-spacing:0.03em;
}