/rails-guides

A Ruby on Rails Traslation Guide

Primary LanguageCSS

Ruby on Rails Guides 中文指南

如果你也想为 Ruby on Rails 社区出一份力就从这里开始吧!

http://guides.ruby-china.org

Rails Guides 中文

Rails Guides 中文是由 docrails 中的 guides 修改而来,你可以在这里 找到官方的原版 Ruby on Rails Guides。Rails Guides 中文目前开源的共享在 github上,你可以根据协议使用并且修改它,Rails Guides 中文希望能为任何热爱 Ruby on Rails 的朋友提供一个共享的文档平台,文章的作者对文章保有一切权利。

加入翻译

目前首页的文章大都是出自 Rails Guides,尚未完全翻译,你可以按照以下的步骤进行认领提交。在认领之前,你需要先到我们的 github 上 fork 一份, 建议使用 textile 进行写作。

认领制度

不管你是要翻译原有文章,还是希望添加一些你觉得非常有用的译文,都应该在翻译之前进行翻译认领来保证没有人和你重复工作。很简单,只要在 source/documents_CN.yaml 中找到或者加入你想翻译的文章的资料,

加入:

work_in_progress: true
contributor: +your_github_acount+

之后,发个 pull request 过来就代表你成功的占到了一个坑,你可以开始慢慢的翻译自己的文章了。

你可以在 contributor 一栏中加入自己的 github 用户名,以便其他人可以联系到你。另外如果你占坑太久你的占位可能会被取消。尽量在半个月内完成你的工作。

关于写作

Rails Guides 中文用了一些关键字来让你的文章生成更加便捷。

Markdown 和 Textile

你可以自行选择使用 Markdown 或者 Textile 语法进行编写,你可以在这两个地方找到他们的基本语法规则。

概要

每篇文章都必须要有一个 h2 的大题目和一份概要,并且以 endprologue. 结尾,在 endprologue. 关键字之前的部分将会生成文章的顶部部分。

标题和目录

除了题目的 h2 (只能用一个)以外你可以用 h3 ~ h6 来让你的文章看起来更有章法,脚本会自动的为你的标题添加 id 和章节索引。

标签

除了提供的 markdown 或者 textile 语法支持,还有一些额外的处理,以这些词开头的段落(关键词后面要跟上一个冒号)将会处理成代标签的文本块。

特殊字符

你如果想要显示一些特殊字符,你可以在字符的两边分别加上一个加号 +,加号中间的部分将会被 textile或者markdown跳过处理。特殊字元参照markdown或者textile语法中的相应部分。

代码

你可以用一对关闭的标签号 <xxx> 和 </xxx> 包围你的代码来为你提供对应的语法高亮和代码块效果。

xxx包括以下关键字:

  • yaml
  • shell
  • ruby
  • erb
  • html
  • sql
  • plain
文章与链接

source/ 下面的 documents_CN.ymal 标注出了所有首页的文章和首页索引,当你写完了一篇文章你可以在那里加入自己的文章的介绍,工作进度,从属类别,标题等来让首页可以链接到你的文章。

例如:

name: 控制器
documents:   
name: Action Controller Overview
url: action_controller_overview.html(你的文件名)
work_in_progress: true #如果加入这一栏说明你正在更新或者对他进行写作
contributor: ME #这里可以写上你的 github 帐号名	
description:  这里是描述
翻译约定
  • 专有名词保持大写:HTML, HAML, SASS, REST...等等。

  • 英文及数字夹在中文之间显得薄弱的关系,之间保留 1 格的空格:大家都来翻译 Rails 指南吧,Rails 目前版本为 3.2.2。

  • 代码与文字之间保留1格: `rvm` 是 Ruby 的版本管控工具。

由于没有照字母顺序排序的关系,建议你使用浏览器的搜索(ctrl+F, cmd+F)来寻找名词。

  • 英文数字与中文之间要留空格。

** 约定翻译的名词:**

原文 中文
class 类别
object 对象
instance 实例
instantiate 实例化
instance variable 实例变量
local variable 局域变数
inherit 继承
interface 接口
library 函式库
server 服务器
database 数据库
(database)table 数据表
code 代码
command-line 命令行
terminal 终端机
method 方法
application 应用程序、应用
framework 框架
template 模版
layout 版型
request 请求
timestamp 时间戳章
form 表单
array 数组
iterate 迭代
escaped 逸出
tag 标签
attribute 属性
routing 路由
collection 集合
macro
保留不译的名词:

... 基本上 Rails、Ruby 有的特有名词,除了计算机科学中常见的词儿以外,在不造成读者困扰的情况下,尽量保持原汁原味。

原文 说明
ActiveXXX 比如 ActiveRecord
resource 资源
partial 片段的 view
schema 资料库纲要
migration 资料库迁移
REST
helper 辅助的 Ruby 代码
scaffold 鹰架
mock 行为驱动测试用词
stub 行为驱动测试用词
param 参数
Rake 任务
Cucumber 不是小黄瓜
validator 验证器

还有一些特殊的标记单词也不要翻译。 在这些标记单词后面的内容在生成 HTML 后会有特殊样式:

WARNING 警告
TIP 提示
NOTE 注意
生成

使用命令

$> rake generate_guides_CN

就可以生成 source/CN 文件夹下的所有 markdowntextile 文档到 output/CN 下。 后缀可以是 .markdown 或者 .md 或者 .textile

部署

文档使用了 capistrano 来进行自动化部署。 在部署之前你需要修改 config/deploy.rb,设置你的用户名与决定部署的路径等。 之后只要每次运行


cap deploy:setup
cap deploy

即可自动完成.

建议与反馈

欢迎任何建议!直接开一个 github issues 就可以了,当然你也可以跑到 Ruby China 社区上面去吐槽,我想这问题不大~

勘误

有翻译就有错误或者语义不清的情况,希望大家有爱一点,别太固执,在有错误或者认为翻译不周的时候你可以开一个 issue 提出,当然更好的方法是直接密翻译者提醒其修改或者 fork 翻译者一份进行修改提交。除非是明显的错误(错别字或者语法错误),我们会坚持 译者的权利,请不要提交一份修改别人翻译的 commit。

如果你发现文档已经过时了,你也可以提出 issue 来修正,我们会提醒翻译者进行翻修,并对读者提出警告的。

感谢

感谢有爱的 Ruby 社区,感谢各路大神为我们分享的文档,感谢每一个热爱并支持 Ruby on Rails 的朋友。

译文来源

https://github.com/lifo/docrails

译文协议

内容采用创用 CC 授权释出

Creative Commons License

有什么问题可以联系我mailto:cool.zhikai@gmail.com.